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APIs by category 


LDAP API Overview 


Lightweight Directory Access Protocol (LDAP) is an Internet protocol to access directory servers. The 
directories on the Internet may be "pure" LDAP directories; that is, they only communicate through LDAP, 
or they may be X.500 or other types of servers that allow access through LDAP. Access to servers that are 
not pure LDAP servers is accomplished through an LDAP gateway. Gateways from LDAP to other 
protocols also are common. Client programs that allow a user to access an LDAP directory are called 
LDAP clients. Applications that extract information from an LDAP directory are referred to as 
LDAP-enabled. 


The LDAP client is part of the OS/400. The LDAP client is used by OS/400 and customer applications for 
access to LDAP-enabled directories in the network. The directories being accessed may or may not be 
located on an OS/400 server. The applications access the LDAP client by using these client APIs. TCP/IP is 
always used to access remote directories, and the administrator can configure the connection to use the 
Secure Sockets Layer (SSL). Also, the administrator can select to use Kerberos. 


The LDAP APIs are designed to provide a suite of functions that can be used to develop directory enabled 
applications. Directory-enabled applications typically connect to one or more directories and perform 
various directory-related operations, such as: 


e Adding entries 

e Searching the directory and obtaining the resulting list of entries 
e Deleting entries 

e Modifying entries 

e Renaming entries 


The type of information that is managed in the directory depends on the nature of the application. 
Directories are often used to provide public access to information about people, including: 


e Phone numbers 
e E-mail addresses 
e Fax numbers 


e Mailing addresses 


Increasingly, directories are being used to manage and publish other types of information, including: 
e Configuration information 
e Public key certificates (managed by certification authorities) 
e Access control information 
e Locating information (how to find a service) 
The LDAP APIs provide for both synchronous and asynchronous access to a directory. Asynchronous 


access makes it easy for your application to do other work while waiting for the results of a potentially 
lengthy directory operation to be returned by the server. 


Typical API Usage 


The basic interaction is as follows. A connection is made to an LDAP server by calling Idap_init (or 
Idap_ssl_init, which is used to establish a secure connection over Secure Sockets Layer (SSL)). 


An LDAP bind operation is performed by calling Idap_simple_bind or Idap_sasl_bind. The bind 
operation is used to authenticate to the directory server. Note that the LDAP V3 API and protocol permits 


the bind to be skipped, in which case the access rights associated with anonymous access are obtained. 


Next, other operations are performed by calling one of the synchronous or asynchronous routines (that is, 
Idap_search_s or Idap_search followed by Idap_result). 


Results returned from these routines are interpreted by calling the LDAP parsing routines, which include 
operations such as: 

e lIdap_first_entry, ldap_next_entry 

e Idap_get_dn 

e ldap_first_attribute, ldap_next_attribute 

e Idap_get_values 

e |dap_parse_result (new for LDAP V3) 


@ etc. 
The LDAP connection is terminated by calling Idap_unbind. 


The Idap_set_rebind_proc routine can be used to define the entry-point of a routine to be called when an 
LDAP bind operation needs to occur when handling a client referral to another server. 


Displaying Results 


Results obtained from the ldap search routines can be accessed by calling Idap_first_entry and 
Idap_next_entry to step through the entries returned, Idap_first_attribute and Idap_next_attribute to 
step through an entry's attributes, ldap_get_values to retrieve a given attribute's value, and then calling 
printf or some other display or usage method to display the values. 


Uniform Resource Locators (URLS) 


The Idap_is_Idap_url routines can be used to test a URL to see if it is an LDAP URL, to parse LDAP 
URLs into their component pieces, and to initiate searches directly using an LDAP URL. 


Examples of these routines are Idap_url_parse, Idap_url_search_s, and Idap_is_Idap_url. 


Secure Socket Layer (SSL) Support 


The LDAP APIs have been extended to support connections that are protected by the Secure Socket Layer 
(SSL) protocol. This can be used to provide strong authentication between the client and server, as well as 
data encryption of LDAP messages that flow between the client and the LDAP server. The 
Idap_ssl_client_init() and Idap_ssl_init() APIs are provided to initialize the SSL function, and to create a 
secure SSL connection (respectively). 


When using Idap_ssl_client_init(), the application ID used is QIBM_GLD_DIRSRV_CLIENT, identified 
as client application "Directory Services Client" in Digital Certificate Manager (DCM). To use OS/400 
application IDs other than the default which have an association to a certificate store and a particular 
certificate in that store, the following OS/400-specific APIs are provided: 


Version 2 API 


e |Idap_app_ssl_start_np() (deprecated) 


Version 3 API 
e Idap_app_ssl_client_init_npQ 


When using Idap_ssl_init(), the server is not contacted until the connection is used; that is, by Idap_bind() 
or Idap_search(). If an SSL error occurs while trying to connect, the SSL error code can be retrieved for the 
connection with the ldap_get_option() API using the LDAP_OPT_EXT_ERROR option. 
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LDAP Version Support 


The LDAP toolkit has been enhanced to support both LDAP Version 2 and LDAP Version 3 APIs and 
protocols. The LDAP toolkit APIs and protocols are based on the Internet Draft, which is classified as a 
"work in progress." 


The LDAP APIs provide typical directory functions such as read, write, and search. With the advent of 
support for LDAP Version 3 APIs and protocols, the following features are also supported: 


e LDAP V3 referrals 


e Improved internationalization with UTF-8 support for Distinguished Names (DNs) and strings that 
are passed into, and returned from the LDAP APIs (when running as an LDAP V3 application and 
LDAP_OPT_UTF8_IO is set to LDAP_UTF8_XLATE_OFF). The default, when running as an 
LDAP V3 or V2 application, for DNs and strings that are passed into or returned from LDAP APIs 
is limited to the local codepage character set. 


In general, the connection-associated LDAP Version 3 APIs ( APIs that have Id as one of their 
parameters ) are designed to accept and return string data in either UTF-8 encoded format or in the 
local code page format, depending on the LDAP_OPT_UTFS8_IO option value set using the 
Idap_set_option() API to LDAP_UTF8_XLATE_ON (the default) or 


LDAP_UTF8_XLATE_OFF. 


The following LDAP APIs (and related APIs) accept and return UTF-8 encoded string data when 
the LDAP_OPT_UTFS8_IO option is set to LDAP_UTF8_XLATE_OFF. Otherwise, they accept 
or return string data in the local code page (the default). 


o Idap_add (and family) 
Idap_bind (and family) 
Idap_compare (and family) 
Idap_delete (and family) 
Idap_parse_reference_np 
Idap_get_dn 
Idap_get_values 
Idap_modify (and family) 
Idap_parse_result 
ldap_rename (and family) 


Idap_search (and family) 


OO 000 000 0 0 0 


Idap_url_search (and family) 


APIs that are NOT associated with a connection (APIs that do not have Id as one of their 
parameters), always expect and return string data (DNs, for example) in local code page. 
The following LDAP APIs (and related APIs) will accept and return string data in the local code 


page. 
Idap_init 
Idap_ssl_init 
Idap_explode_dn 
Idap_explode_rdn 


O 0 0 0 0 


Idap_server_locate 


o Idap_server_conf_save 

o Idap_is_Idap_url 

o Idap_default_dn_set/get 
As a non-standard extension to the API set on OS/400 only, two APIs have been added that allow 
input of string data in UTF8. These are: 

o Idap_explode_dn_utf8 

o Idap_explode_rdn_utf8 


e The ability for an application to access schema information published by LDAP V3 servers (see 
Accessing Schema Information). 


e The ability for certain LDAP Version 3 operations to be extended with the use of controls. 
Controls can be sent to a server, or returned to the client with any LDAP message. This type of 
control is called a server control. 


The LDAP API also supports a client-side extension mechanism, which can be used to define client 
controls. The client-side controls affect the behavior of the LDAP client library, and are never sent 
to the server. Note that client-side controls are not defined for this client library. 


A common data structure is used to represent both server-side and client-side controls: 


typedef struct ldapcontrol { 


char *ldctl_oid; 
struct berval ldctl_value; 
char ldctl_iscritical; 


} LDAPControl, *PLDAPControl; 


The LDAPControl fields have the following definitions: 
Idctl_oid 
The control type, represented as a string. 
Idctl_value 
The data associated with the control. The control may not include data. 
Idctl_iscritical 
Whether the control is critical or not. If the field is non-zero, the operation is carried out 


only if it is recognized and supported by the server (or the client for client-side controls). 


If using any of the ber_xxx functions to set up the berval structure, you must specify 
QSYS/QGLDBRDR as one of the the bind service programs when creating the program. 


With this toolkit, an application that uses the Idap_open API defaults to the LDAP V2 protocol. In this 
way, existing LDAP applications will continue to work, and can interoperate with both LDAP V2 servers 
and LDAP V3 servers. 


An application that uses the Idap_init API defaults to the LDAP V3 protocol (with optional bind). An 
LDAP V3 application will not necessarily interoperate with an LDAP server that supports only LDAP V2 
protocols. 


An application can use the Idap_set_option API to change its LDAP protocol version. This should be done 
after using Idap_open or Idap_init but before issuing a bind or other operation that results in contacting the 
server. 
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Accessing Schema Information 


LDAP V3 servers permit applications to access schema and other related information. For example, the 
ldapsearch utility can be used to obtain the subschemasubentry, attributeTypes, and objectClasses from 
IBM's Secure Way Directory Server. First use ldapsearch to get the root DSE to find the entry containing 
the schema (called the subschemasubentry) for the server, as follows: 


ldapsearch -V 3 -h hostname -p port 
-s base -b "™" "objectClass=*" subschemaSubentry 


The subschemasubentry on SecureWay directories is cn=schema by default. To retrieve the schema itself, 
search on the subschemasubentry entry, as follows: 


ldapsearch -V 3 -h hostname -p port 
-s base -b "cn=schema" "“objectclass=*" 


The "-V 3" option is used to force Idapsearch to bind as an LDAP V3 application. 
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API Prototype Changes 


For many of the LDAP APIs, the prototype has changed. On many of the API prototypes where a ''char *"' 
is used, the prototype has changed to use a "const char *"'. This is the result of changes to the standards. 
OS/400 is providing a way to transition to the new prototypes. Inserting 


#define QGLDNOCONST 
in applications code prior to the include of Idap.h causes the definition of the old prototypes that use "char 
*" to be made available. If QGLDNOCONST, which is the default, is not defined, the definition of the 


new prototypes that use ''const char *"' is made available. 


In some future release, the use of QGLDNOCONST will be withdrawn. 
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Deprecated APIs 


The following is a list of APIs that are still supported, although their use is deprecated. Use of the newer 
replacement APIs is strongly encouraged. 


e Idap_ssl_start() - use Idap_ssl_client_init() and Idap_ssl_initQ 
Idap_open() - use Idap_init() 

Idap_bind() - use Idap_simple_bind() 

Idap_bind_s() - use Idap_simple_bind_s() 

Idap_modrdn() - use Idap_rename() 

Idap_modrdn_s() - use ldap_rename_s() 

Idap_result2error() - use Idap_parse_result() 


Idap_perror() - use Idap_parse_result() 


OS/400-specific APIs: 
e Idap_app_ssl_start_np() - use Idap_app_ssl_client_init_np(Q) and Idap_app_ssl_init_np(). 
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LDAP Client API Error Conditions 


When most LDAP APIs fail to complete successfully, ld_errno usually indicates one of the following 
errors. Under some conditions, Id_errno could indicate an error other than those listed here. 


LDAP_SUCCESS 0x00 - The request was successful. 
LDAP_OPERATIONS_ERROR 0x01 - An operations error occurred. 
LDAP_PROTOCOL_ERROR 0x02 - A protocol violation was detected. 
LDAP_TIMELIMIT_EXCEEDED 0x03 - An LDAP time limit was exceeded. 
LDAP_SIZELIMIT_EXCEEDED 0x04 - An LDAP size limit was exceeded. 
LDAP_COMPARE_FALSE 0x05 - A compare operation returned false. 
LDAP_COMPARE_TRUE 0x06 - A compare operation returned true. 
LDAP_STRONG_AUTH_NOT_SUPPORTED 0x07 - The LDAP server does not support strong 
authentication. 
LDAP_STRONG_AUTH_REQUIRED 0x08 = Strong authentication is required for the 
operation. 
LDAP_PARTIAL_RESULTS 0x09 - Partial results only returned. 
LDAP_REFERRAL OXOA - Referral returned. 
LDAP_ADMIN_LIMIT_EXCEEDED OXOB - Administration limit exceeded. 


LDAP_UNAVAILABLE_CRITICAL_EXTENSION OXOC - Critical extension not supported. 


LDAP_NO_SUCH_ATTRIBUTE 0x10 - The attribute type specified does not exist in 
the entry. 

LDAP_UNDEFINED_TYPE 0x11 - The attribute type specified is not valid. 

LDAP_INAPPROPRIATE_MATCHING 0x12 - Filter type not supported for the specified 
attribute. 

LDAP_CONSTRAINT_VIOLATION 0x13 - An attribute value specified violates some 


constraint (for example, a postal address has too 
many lines, or a line that is too long). 


LDAP_TYPE_OR_VALUE_EXISTS 0x14 - An attribute type or attribute value specified 
already exists in the entry. 

LDAP_INVALID_SYNTAX 0x15 - An attribute value was specified that is not 
valid. 

LDAP_NO_SUCH_OBJECT 0x20 - The specified object does not exist in the 
directory. 

LDAP_ALIAS_PROBLEM 0x21 - An alias in the directory points to a 


nonexistent entry. 


LDAP_INVALID_DN_SYNTAX 0x22 - A distinguished name was specified that is 
syntactically not valid. 


LDAP_IS_LEAF 
LDAP_ALIAS_DEREF_PROBLEM 


LDAP_INAPPROPRIATE_AUTH 


LDAP_INVALID_CREDENTIALS 


LDAP_INSUFFICIENT_ACCESS 


LDAP_BUSY 
LDAP_UNAVAILABLE 
LDAP_UNWILLING_TO_PERFORM 


LDAP_LOOP_DETECT 
LDAP_NAMING_VIOLATION 
LDAP_OBJECT_CLASS_VIOLATION 


LDAP_NOT_ALLOWED_ON_NONLEAF 


LDAP_NOT_ALLOWED_ON_RDN 


LDAP_ALREADY_EXISTS 
LDAP_NO_OBJECT_CLASS_MODS 
LDAP_RESULTS_TOO_LARGE 
LDAP_AFFECTS_MULTIPLE_DSAS 
LDAP_OTHER 
LDAP_SERVER_DOWN 


LDAP_LOCAL_ERROR 


LDAP_ENCODING_ERROR 


LDAP_DECODING_ERROR 


0x23 - The object specified is a leaf. 


0x24 - A problem was encountered when 
dereferencing an alias. 


0x30 - Inappropriate authentication was specified 
(for example, LDAP_AUTH_SIMPLE was 
specified and the entry does not have a user 
password attribute). 


0x31 - Credentials that are not valid were presented 
(for example, the wrong password). 


0x32 - The user has insufficient access to perform 
the operation. 


0x33 - The directory system agent is busy. 
0x34 - The directory system agent is unavailable. 


0x35 - The directory system agent is unwilling to 
perform the operation. 


0x36 - A loop was detected. 
0x40 - A naming violation occurred. 


Ox41 - An object class violation occurred (for 
example, a must attribute was missing from the 
entry). 


0x42 - The operation is not allowed on a nonleaf 
object. 


0x43 - The operation is not allowed on a relative 
distinguished name. 


0x44 - The entry already exists. 

0x45 - Object class modifications are not allowed. 
0x46 - Results too large. 

0X47 - Affects multiple DSAS. 

0x50 - An unknown error occurred. 


0x51 - The LDAP API cannot contact the LDAP 
server. 


0x52 - Some local error occurred. This usually 
indicates that either the LDAP support (OS/400 
option 32) is not installed on the system, or a 
malloc() operation has failed 


0x53 - An error was encountered while the API was 
encoding parameters to send to the LDAP server. 


0x54 - An error was encountered while the API was 
decoding a result from the LDAP server. 


LDAP_TIMEOUT 


LDAP_AUTH_UNKNOWN 


LDAP_FILTER_ERROR 


LDAP_USER_CANCELLED 
LDAP_PARAM_ERROR 


LDAP_NO_MEMORY 


LDAP_CONNECT_ERROR 
LDAP_NOT_SUPPORTED 
LDAP_CONTROL_NOT_FOUND 
LDAP_NO_RESULTS_RETURNED 
LDAP_MORE_RESULTS_TO_RETURN 
LDAP_URL_ERR_NOTLDAP 
LDAP_URL_ERR_NODN 
LDAP_URL_ERR_BADSCOPE 
LDAP_URL_ERR_MEM 
LDAP_CLIENT_LOOP 
LDAP_REFERRAL_LIMIT_EXCEEDED 
LDAP_SSL_ALREADY_INITIALIZED 


LDAP_SSL_INITIALIZE_FAILED 
LDAP_SSL_INITIALIZE_NOT_CALLED 


LDAP_SSL_PARAM_ERROR 


LDAP_SSL_HANDSHAKE_FAILED 
LDAP_SSL_GET_CIPHER_FAILED 


LDAP_SSL_NOT_AVAILABLE 
LDAP_SSL_KEYRING_NOT_FOUND 


0x55 - A time limit was exceeded while API was 


waiting for a result. 


0x56 - The authentication method specified to 
Idap_bindQ is not known. 


0x57 - A filter that is not valid was supplied to 
Idap_search() (for example, unbalanced 
parentheses). 


0x58 - User cancelled 


0x59 - An LDAP API was called with a bad 
parameter (for example, a NULL Id pointer). 


Ox5A - A memory allocation (for example, a 
malloc() call) failed in an LDAP API. 


Ox5b - Connection error 

OxSc - Not Supported 

Ox5d - Control not found 

OxSe - No results returned 

Ox5f - More result to return 

0x60 - URL doesn't begin with Idap:// 
0x61 - URL has no DN (required). 
0x62 - URL scope string is invalid. 
0x63 - can't allocate memory space. 
0x64 - Client loop 

0x65 - Referral limit exceeded 


0x70 - Idap_ssl_client_init successfully called 
previously in this process. 


0x71 - SSL initialization call failed. 


0x72 - Call ldap_ssl_client_init before attempting to 


use an ssl connection. 


0x73 - An invalid ssl parameter was previously 
specified. 


0x74 - Failed to connect to ssl server. 


0x75 - Failed to identify the maximum SSL 
encryption level for this host. 


0x76 - The SSL library cannot be loaded. 


0x77 - SSL Keyring file not found 


LDAP_SSL_PASSWORD_NOT_SPECIFIED 
LDAP_NO_EXPLICIT_OWNER 
LDAP_NO_LOCK 
LDAP_DNS_NO_SERVERS 
LDAP_DNS_TRUNCATED 
LDAP_DNS_INVALID_DATA 
LDAP_DNS_RESOLVE_ERROR 


LDAP_DNS_CONF_FILE_ERROR 


LDAP_XLATE_E2BIG 
LDAP_XLATE_EINVAL 
LDAP_XLATE_EILSEQ 
LDAP_XLATE_NO_ENTRY 


LDAP_REG_FILE_NOT_FOUND 


LDAP_REG_CANNOT_OPEN 
LDAP_REG_ENTRY_NOT_FOUND 


LDAP_CONF_FILE_NOT_OPENED 


LDAP_PLUGIN_NOT_LOADED 
LDAP_PLUGIN_FUNCTION_NOT_RESOLVED 
LDAP_PLUGIN_NOT_INITIALIZED 
LDAP_PLUGIN_COULD_NOT_BIND 
LDAP_SASL_GSS_NO_SEC_CONTEXT 


0x78 - SSL password not specified 
0x80 - No explicit owner found 

Ox81 - Could not obtain lock 

0x85 - No LDAP servers found 

0x86 - Warning truncated DNS results 
0x87 - Invalid DNS Data 

0x88 - Can't resolve system domain or nameserver 
0x89 - DNS Configuration file error 
OxAO - Output buffer overflow 

OxA1 - Input buffer truncated 

OxA2 - Unusable input character 
OxA3 - No codeset point to map to 
OxBO - NT Registry - file not found 


OxB1 - NT Registry - cannot open 


OxB2 - NT Registry entry not found 

OxCO - Plugin configuration file not opened 
OxCl1 - Plugin library not loaded 

OxC2 - Plugin function not resolved 

OxC3 - Plugin library not initialized 

OxC4 - Plugin function could not bind 


OxDO - gss_init_sec_context failed 
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Controls for LDAP APIs 


Certain LDAP Version 3 operations can be extended with the use of controls. Controls can be sent to a 
server, or returned to the client with any LDAP message. This type of control is called a server control. 


The LDAP API also supports a client-side extension mechanism, which can be used to define client 
controls. The client-side controls affect the behavior of the LDAP client library, and are never sent to the 
server. Note that client-side controls are not defined for this client library. 


A common data structure is used to represent both server-side and client-side controls: 


typedef struct ldapcontrol { 


char *ldctl_oid; 
struct berval ldctl_value; 
char ldctl_iscritical; 


} LDAPControl, *PLDAPControl; 
The LDAPControl fields have the following definitions: 
Idctl_oid The control type, represented as a string. 
Idctl_value The data associated with the control. Note that the control may not include data. 


Idctl_iscritical Whether the control is critical. If the field is nonzero, the operation will be carried out 
only if it is recognized and supported by the server (or the client for client-side 
controls). 
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Idap_abandon()--Abandon an LDAP Operation 
in Progress 


Syntax 


#include <ldap.h> 


int ldap_abandon ( 
LDAP *1d, 


int msgid) 


Library Name/Service Program: QS YS/QGLDCLNT 
Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_abandon() function is used to abandon or cancel an LDAP operation in progress. The msgid 
passed should be the message ID of an outstanding LDAP operation, as returned by a call to an 
asynchronous LDAP operation such as Idap_search(), Idap_modify(Q), and so on. 

The Idap_abandon() APIs check to see if the result of the operation has already been returned by the 
server. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon 
operation to the the LDAP server. 


The caller can expect that the result of an abandoned operation will not be returned from a future call to 
Idap_result(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


msgid 


(Input) The message ID of an outstanding LDAP operation, as returned by a call to an 
asynchronous LDAP operation such as ldap_search() or Idap_modifyQ. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


-1 


if the request was not successful. 


Error Conditions 


If ldap_abandon() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error codes values and Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_abandon API. 


Related Information 


e Idap_abandon_ext() -- Abandon (abort) an asynchronous operation with controls. 


API introduced: V4R3 
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Idap_abandon_ext()--Abandon (abort) an 
Asynchronous Operation with Controls 


Syntax 


#include <ldap.h> 


int ldap_abandon_ext ( 
LDAP *ld, 
int msgid, 
LDAPControl *xserverctrls, 
LDAPControl **xclientctrls) 


Library Name/Service Program: QS YS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_abandon_ext() function is used to abandon or cancel an LDAP operation in progress. The msgid 
passed should be the message ID of an outstanding LDAP operation, as returned by a call to an 
asynchronous LDAP operation such as Idap_search(), Idap_modify(), and so on. 

This API checks to see if the result of the operation has already been returned by the server. If it has, the 
result is removed from the queue of pending messages. If not, it sends an LDAP abandon operation to the 
the LDAP server. 


The caller can expect that the result of an abandoned operation will not be returned from a future call to 
Idap_result(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


msgid 


(Input) The message ID of an outstanding LDAP operation, as returned by a call to an 
asynchronous LDAP operation such as Idap_search or Idap_modify. 


serverctrls 


(Input) A list of LDAP server controls. This parameter may be set to null. See LDAP Controls for 
more information about server controls. 


clientctrls 


(Input) A list of LDAP client controls. This parameter may be set to null. See LDAP Controls for 
more information about client controls. 


Return Value 


LDAP_SUCCESS 
if the Idap_abandon() was successful. 


Other LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_abandon_ext() is not successful, LDAP error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 
Message ID_ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_abandon_ext API. 


Related Information 


e idap_abandonQ) -- Abandon (abort) an asynchronous operation. 


API introduced: V4R5 
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Idap_add()--Perform an LDAP Add Operation 


Syntax 


#include <ldap.h> 


int ldap_add ( 
LDAP * 1d; 
const char *dn, 
LDAPMod **xattrs) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_add() function is used to perform an LDAP add operation. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 


dn 
(Input) The DN of the entry to add. 


attrs 


(Input) The entry's attributes, specified using the LDAPMod structure, as defined for 
Idap_modifyQ. The mod_type and mod_vals fields should be filled in. The mod_op field is ignored 
unless ORed with the constant LDAP_MOD_BVALUES. In this case, the mod_op field is used to 
select the mod_bvalues case of the mod_vals union. 


Return Value 
Message ID of the operation initiated 


if the request was successfully sent. A subsequent call to Idap_result(), can be used to obtain the 
result of the operation. 


z 


if the request was not successful. 


Error Conditions 


If ldap_add() is not successful, Jd_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values and Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_add API. 


Related Information 


e Idap_add_s(Q) -- Synchronously add an entry. 
e Idap_add_ext() -- Asynchronously add an entry with controls. 


e@ Idap_add_ext_s() -- Synchronously add an entry with controls. 
e idap_modifyQ -- Asynchronously modify an entry. 


API introduced: V4R3 
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Idap_add_ext()--Perform an LDAP Add 
Operation with Controls 


Syntax 


#include <ldap.h> 


int ldap_add_ext ( 
LDAP * 1d, 
const char *dn, 
LDAPMod *xattrs, 
LDAPControl **serverctrls, 
LDAPControl **clientctrls, 
int xmsgidp) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_add_ext() function is used to perform an LDAP add operation with controls. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


dn 
(Input) The DN of the entry to add. 

attrs 
(Input) The entry's attributes, specified using the LDAPMod structure, as defined for 
Idap_modifyQ. The mod_type and mod_vals fields should be filled in. The mod_op field is ignored 
unless ORed with the constant LDAP_MOD_BVALUES. In this case, the mod_op field is used to 
select the mod_bvalues case of the mod_vals union. 

serverctrls 


(Input) A list of LDAP server controls. This parameter may be set to null. See LDAP Controls for 


more information about server controls. 


clientctrls 


(Input) A list of LDAP client controls. This parameter may be set to null. See LDAP Controls for 
more information about client controls. 


msgidp 


(Output) This result parameter is set to the message ID of the request if the Idap_add_ext() call 
succeeds. 


Return Value 


LDAP_SUCCESS 


if the request was successful. If successful, ldap_add_ext() places the message ID of the request in 
*msgidp. A subsequent call to ldap_resultQ can be used to obtain the result of the operation. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_add_ext() is not successful, an LDAP error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error code values. The error code indicates if the operation completed 
successfully. The ldap_parse_result() API is used to check the error code in the result. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_add_ext API. 


Related Information 


e Idap_addQ -- Asynchronously add an entry. 
e Idap_add_s(Q) -- Synchronously add an entry. 


e@ Idap_add_ext_s() -- Synchronously add an entry with controls. 


e idap_modify_extQ -- Asynchronously modify an entry with controls. 


The Idap_add_ext() API supports LDAP V3 server controls and client controls. 


API introduced: V4R5 
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Idap_add_ext_s()--Perform an LDAP Add 
Operation with Controls (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_add_ext_s (LDAP «1d, 
const char *dn, 
LDAPMod k*xattr, 
LDAPControl **serverctrils, 
LDAPControl **clientctrls) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_add_ext_s() function is used to perform synchronous LDAP add operation with controls. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 


dn 
(Input) The DN of the entry to add. 

attrs 
(Input) The entry's attributes, specified using the LDAPMod structure, as defined for 
Idap_modifyQ. The mod_type and mod_vals fields should be filled in. The mod_op field is ignored 
unless ORed with the constant LDAP_MOD_BVALUES. In this case, the mod_op field is used to 
select the mod_bvalues case of the mod_vals union. 

serverctrls 


(Input) A list of LDAP server controls. This parameter may be set to null. See LDAP Controls for 
more information about server controls. 


clientctrls 


(Input) A list of LDAP client controls. This parameter may be set to null. See LDAP Controls for 
more information about client controls. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_add_ext_s() will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_add_ext_s API. 


Related Information 


e Idap_addQ) -- Asynchronously add an entry. 
e idap_add_s() -- Synchronously add an entry. 
e Idap_add_ext() -- Asynchronously add an entry with controls. 


e Idap_modify_ext_sQ -- Synchronously modify an entry with controls. 


The Idap_add_ext_s() API supports LDAP V3 server controls and client controls. 


API introduced: V4R5 
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Idap_add_s()--Perform an LDAP Add Operation 
(Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_add_s ( 
LDAP * 1d; 
const char *dn, 
LDAPMod **xattrs) 


Library Name/Service Program: QS YS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_add_s() function is used to perform synchronous LDAP add operation. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_init(), ldap_ssl_initQ), or ldap_openQ. 


dn 
(Input) The DN of the entry to add. 


attrs 
(Input) The entry's attributes, specified using the LDAPMod structure, as defined for 
Idap_modifyQ. The mod_type and mod_vals fields should be filled in. The mod_op field is ignored 


unless ORed with the constant LDAP_MOD_BVALUES. In this case, the mod_op field is used to 
select the mod_bvalues case of the mod_vals union. 


Return Value 


LDAP_SUCCESS 


if the request was successfully sent. 


another LDAP error code 


if the request was not successfully sent. 


Error Conditions 


If ldap_add_s() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_add_s API. 


Related Information 


e Idap_addQ -- Asynchronously add an entry. 
e@ Idap_add_ext_s() -- Synchronously add an entry with controls. 


e@ Idap_add_ext() -- Asynchronously add an entry with controls. 


e idap_modify_sQ -- Synchronously modify an entry. 


API introduced: V4R3 
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Idap_app_ssl_client_init_np()--Initialize the 
LDAP Client for a Secure Connection using 
DCM 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


int ldap_app_ssl_client_init_np ( 
char *dcm_identifier, 
int *pSSLReasonCode) 


Library Name/Service Program: QS YS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_app_ssl_client_init_npQ is an LDAP V3 function used to initialize the LDAP client using the 
Digital Certificate Manager (DCM) to control the digital certificate in preparation for making a secure 
connection (using Secure Sockets Layer (SSL)) to a LDAP server. 


Idap_app_ssl_client_init_npQ must be called prior to lIdap_app_ssl_init_npQ to establish a connection, and 
prior to any kind of Idap_bindQ), whether it be an Idap_sasl_bind_sQ or an Idap_simple_bind_s(Q). 
Idap_app_ssl_client_init_np() must be called only once per job, while multiple Idap_app_ssl_init_npQ or 
secure connections can be done, allowing one (DCM) initialization to be done for many connections. Once 
the secure connection is established all subsequent LDAP messages that flow over the secure connection are 
encrypted, including the Idap_bind() parameters, until Idap_unbindQ is called. 


Either Idap_ssl_client_init) or ldap_app_ssl_client_init_np(Q) (but not both) can be called in an application 
process. If you are not going to use SSL client authentication (LDAP SASL bind with the EXTERNAL 
mechanism), use ldap_ssl_client_init(). 


Authorities and Locks 


*R authority is needed to the selected Certificate Store and *X to the associated directories. 


Parameters 


dcm_identifier 


(Input) An identifier string that corresponds to a secure application registered with DCM. If NULL is 
used, then the default Directory Services client application ID will be used 
(QIBM_GLD_DIRSRV_CLIENT). 


pSSLReasonCode 


(Output) A pointer to the SSL Reason Code, which provides additional information in the event that 
an error occurs during initialization of the SSL stack (when Idap_app_ssl_client_init_np(Q) is 
called). See QSYSINC/H.LDAPSSL for reason codes that can be returned. 


Examples 


The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions 
are "protected" by using a secure SSL connection: 


re ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode) ; 
ld ldap_app_ssl_init_np(ldaphost, ldapport ); 
re = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers); 
re = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, 
NULL, NULL ); 


...additional LDAP API calls 
re = ldap_unbind( ld ); 


The following scenario depicts the calling sequence for multiple connections using one DCM identifier: 


rc = ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode) ; 
ld = ldap_app_ssl_init_np(ldaphost, ldapport ); 
rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers) ; 
re = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, 
NULL, NULL ); 


/* For multiple secure connections using the same dcm_identifier. */ 


ldl = ldap_app_ssl_init_np(ldaphost, ldapport ); 
re = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, 
NULL, NULL ); 


1ld2 = ldap_app_ssl_init_np(ldaphost, ldapport ); 
re = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, 
NULL, NULL ); 


-additional LDAP API calls 


re = ldap_unbind( ld ); 
ldap_unbind( ldl ); 
re = ldap_unbind( l1d2 ); 


H 
Q 
ll 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If lIdap_app_ssl_client_init_npQ is not successful it will return an LDAP error code. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID_ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_ssl_client_init_np API. 


Related Information 


e Idap_app_ssl_init_npQ -- Initializes an SSL Connection. 
e Idap_app_ssl_start_npQ -- Start a Secure LDAP Connection using DCM. 


e Idap_ssl_client_initQ -- Initializes the SSL Library. 

e lIdap_ssl_init( -- Initializes an SSL connection. 

e lIdap_ssl_start() -- Creates a secure SSL connection (deprecated). 
e Idap_bindQ -- Bind to the directory server. 


e Idap_sasl_bind_sQ) -- Synchronously bind to the directory using Simple Authentication Security 
Layer (SASL). 
e idap_unbindQ -- unbind from the LDAP server and close the connection. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_app_ssl_init_np --Initializes an SSL 
Connection 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


LDAP *ldap_app_ssl_init_np ( 
char *host, 
int port) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_app_ssl_init_np() routine is used to initialize a secure SSL session with a server. Note that the 
server is not actually contacted until an operation is performed that requires it, allowing various options to 
be set after initialization. Once the secure connection is established, all subsequent LDAP messages that 
flow over the secure connection are encrypted, including the Idap_simple_bindQ parameters, until 


Idap_unbindQ is called. 


Note that when connecting to an LDAP V2 server, one of the Idap_simple_bindQ or Idap_bindQ calls must 


be completed before other operations can be performed on the session (with the exception of 
Idap_set/get_optionQ). The LDAP V3 protocol does not require a bind operation before performing other 


operations. 


The ciphers for the encryption of the connection are based on the current Crypto Access Provider licensed 
program loaded: AC1, AC2 or AC3. See Idap_get or set_optionQ for more information on setting the 


ciphers to be used. 


Authorities and Locks 


*R authority is needed to the selected Certificate Store and *X to the associated directories. 


Parameters 


host 


(Input) Several methods are supported for specifying one or more target LDAP servers, including 
the following: 


Explicit Host List Specifies the name of the host on which the LDAP server is 
running. The host parameter may contain a blank-separated list of 
hosts to try to connect to, and each host may optionally be of the 
form host:port. If present, the :port overrides the port parameter. 


The following are typical examples: 


ld=ldap_app_ssl_init_np (server1", ldaps_port); 
ld=ldap_app_ssl_init_np ("server2:1200", Idaps_port); 
ld=ldap_app_ssl_init_np ("server1:800 server2:2000 server3", 
Idaps_port); 


Localhost If the host parameter is null, it is assumed that the LDAP server is 
running on the local host. 


Default Hosts If the host parameter is set to "Idaps://" the LDAP library will 
attempt to locate one or more default LDAP servers, with SSL 
ports, using the SecureWay Idap_server_locate() function. The port 
specified on the call is ignored, since Idap_server_locate() returns 
the port. 


For example, the following two are equivalent: 


Id=ldap_app_ssl_init_np ("Idaps://", Idaps_port); 
Id=Idap_app_ssl_init_np (LDAPS_URL_PREFIX, 
LDAPS_PORT); 


If more than one default server is located, the list is processed in 
sequence, until an active server is found. 


The LDAP URL can include a Distinguished Name, used as a filter 
for selecting candidate LDAP servers based on the server's suffix 
(or suffixes). If the most significant portion of the DN is an exact 
match with a server's suffix (after normalizing for case), the server 
is added to the list of candidate servers. For example, the following 
will only return default LDAP servers that have a suffix that 
supports the specified DN: 


Id=Idap_app_ssl_init_np ("Idaps:///cn=fred, dc=austin, dc=ibm, 
dc=com", LDAPS_PORT) 


In this case, a server that has a suffix of "dc=austin, dc=ibm, 
dc=com" would match. If more than one default server is located, 
the list is processed in sequence, until an active server is found. 


If the LDAP URL contains a host name and optional port, the host 
is used to create the connection. No attempt is made to locate the 
default server(s), and the DN, if present, is ignored. 


For example, the following two are equivalent: 


ld=ldap_app_ssl_init_np ("Idaps://myserver", LDAPS_PORT); 
Id=Idap_app_ssl_init_np ("myserver", LDAPS_PORT); 


port 


Local Socket If the host parameter is prefixed with "/", the host parameter is 
assumed to be the name of a UNIX socket (that is, socket family is 
AF_UNIX) and port is ignored. This will fail for 
Idap_app_ssl_init_np(Q) because UNIX sockets do not support SSL, 


nor is it necessary since data will not be flowing over the network. 


If a specified host is prefixed with "privport://", then the LDAP 
library will use the rresvport() function to attempt to obtain one of 
the reserved ports (512 through 1023), instead of an "ephemeral" 
port. The search for a reserved port starts at 1023 and stops at 512. 
If a reserved port cannot be obtained, Idap_app_ssl_init_np() will 
fail. 


Host with Privileged Port 


For example: 


Id=ldap_app_ssl_init_np ("privport://server1, ldaps_port"); 
Id=ldap_app_ssl_init_np ("privport://server2: 1200", Idaps_port); 
Id=ldap_app_ssl_init_np ("privport://server1:800 server2:2000 
privport://server3", Idaps_port); 


(Input) The port number to which to connect. If the default [ANA-assigned SSL port of 636 is 
desired, LDAPS_PORT should be specified. The value specified for this parameter is ignored in 
some situations; see the description for the host parameter. 


Return Value 


Session Handle 


NULL 


if the request was successful. The Session Handle returned by Idap_app_ssl_init_np() is a pointer 
to an opaque data type representing an LDAP session. The ldap_get_option() and Idap_set_option() 
APIs are used to access and set a variety of session-wide parameters; see these APIs for more 
information. 


if the request was not successful. 


Error Conditions 


Idap_app_ssl_init_npQ) will return NULL if not successful. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_app_ssl_init_np API. 


Related Information 


e Idap_app_ssl_client_init_npQ -- Initialize the Client for a Secure LDAP Connection using DCM. 


e Idap_ssl_client_initQ -- Initializes the SSL library. 
e |dap_app_ssl_start_npQ -- Creates a secure SSL connection (deprecated). 
e Idap_ssl_start() -- Creates a secure SSL connection (deprecated). 


Example 


The following scenario depicts the recommended calling sequence where the entire set of LDAP 
transactions are protected by using a secure SSL connection: 


re ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode) ; 
ld ldap_app_ssl_init_np(ldaphost, ldapport ); 
re = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers); 
re = ldap_sasl_bind_s( 1d, NULL, LDAP_MECHANISM_EXTERNAL, NULL, 
NULL, NULL ); 


...-additional LDAP API calls 


re = ldap_unbind( ld ); 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_app _ ssl_start_np()--Start a Secure LDAP 
Connection using DCM 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


int ldap_app_ssl_start_np(LDAP *ld, 
char *dcm_identifier) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


This is a deprecated API. 


The Idap_app_ssl_start_np() function is used to start a secure connection (using Secure Sockets Layer (SSL)) 
to an LDAP server using the Digital Certificate Manager (DCM) to control the digital certificate. 


Idap_app_ssl_start_np() must be called after l}dap_open() and prior to Idap_bind(). Once the secure 
connection is established for the /d, all subsequent LDAP messages that flow over the secure connection are 
encrypted, including the Idap_bind() parameters, until Idap_unbind() is called. 


Authorities and Locks 


*R authority is needed to the selected Certificate Store and *X to the associated directories. 


Parameters 


Id 


(Input) The LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or ldap_open(). 


dcm_identifier 


(Input) An identifier string that corresponds to a secure application registered with DCM. The use of 
NULL assumes that in a prior use of the this API a valid DCM identifier for an application has been 
used and that it is to be used again for this connection. This allows multiple connections without going 
through the initialization of SSL with a DCM identifier more than once. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


Idap_app_ssl_start_npQ will return an LDAP error code if not successful. See LDAP Client API Error 


Conditions for possible LDAP error code values. Depending on the error code, errno information also may be 


available. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_app_ssl_start_np API. 


Related Information 


e idap_app_ssl_client_init_npQ -- Initialize the Client for a Secure LDAP Connection using DCM 
e Idap_ssl_client_init() -- Initializes the SSL Library 

e Idap_ssl_initQ -- Initializes an SSL connection 

e lIdap_ssl_start() -- Creates a secure SSL connection 

e Idap_bindQ -- Bind to the directory server 

e |dap_unbindQ -- Unbind from the LDAP server and close the connection 

e idap_openQ -- Open a connection to an LDAP server 


Example 


The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions 


are "protected" by using a secure SSL connection, including the dn and password that flow on the 
Idap_simple_bind(): 


1d 
re 
re 


= ldap_open (ldaphost, ldapport ); 
= ldap_app_ssl_start_np(ld, dcm_identifier ); 
= ldap_simple_bind_s(ld, binddn, passwd) ; 


...additional LDAP API calls 
re = ldap_unbind( ld ); 

The following scenario depicts the calling sequence for multiple connections using one DCM identifier: 
ld = ldap_open (ldaphost, ldapport ); 


re ldap_app_ssl_start_np(ld, dcm_identifier ); 
rc = ldap_simple_bind_s(ld, binddn, passwd) ; 


/* For multiple secure connections using the same dcm_identifier. */ 


1ldl = ldap_open (ldaphost, ldapport ); 
re = ldap_app_ssl_start_np(ld1l, NULL ); 
rc = ldap_simple_bind_s(ldl, binddn, passwd) ; 


1d2 = ldap_open (ldaphost, ldapport ); 
rG ldap_app_ssl_start_np(1ld2, NULL ); 
re ldap_simple_bind_s(ld2, binddn, passwd) ; 


-additional LDAP API calls 


re = ldap_unbind( ld ); 
re ldap_unbind( ldl ); 
re = ldap_unbind( 1d2 ); 


API introduced: V4R4 


Top | Directory Services APIs | APIs by category 


Idap_ber_free()--Free storage allocated by the 
LDAP library 


Syntax 


#include <ldap.h> 


void ldap_ber_free ( 
BerElement *berptr) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_ber_free() routine is used to free the BerElement pointed to by berptr. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


berptr 


(Input) The address of the BerElement to be freed, as returned from Idap_first_attribute() and 
Idap_next_attribute(). 


Return Value 


None. 


Error Conditions 


The Idap_ber_free() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 
Message ID _ Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_ber_free API. 


Related Information 


e idap_first_attributeQ -- Retrieve First Attribute in an Entry 
e |dap_next_attribute() -- Retrieve Next Attribute in an Entry 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_bind()--Perform an LDAP Bind Request 


Syntax 


#include <ldap.h> 


int ldap_bind( 
LDAP * 1d; 
const char *dn, 
const char *cred, 
int method) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_bind() function provides general authentication routines, where in principle an authentication 
method can be chosen. In this toolkit, method must be set to LDAP_AUTH_SIMPLE. 


The Idap_bind() function is used to authenticate a distinguished name (DN) to a directory server. When 
connecting to an LDAP V2 server, after a connection is made by using the Idap_open() API, an LDAP 
bind API must be called before any other LDAP APIs can be called for that connection. Binding the 
connection is not required for LDAP V3. 


Idap_bind( is an asynchronous request. The result of the operation can be obtained by a subsequent call to 
Idap_result(). 


Since this API is deprecated, ldap_simple_bind() should be used instead. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


dn 
(Input) The distinguished name of the entry to bind as. 


cred 
(Input) The credentials with which to authenticate. Arbitrary credentials can be passed using this 


parameter. In most cases, this is the user's password. 


method 


(Input) Selects the authentication method to use. Specify LDAP_AUTH_SIMPLE for simple 
authentication. Simple authentication is the only supported method. 


Note that use of the Idap_bind() API is deprecated. 


Return Value 


Message ID of the Initiated Request 
if the Idap_bind() was successful. 


-1 


if the request was not successful. 


Error Conditions 


If Idap_bind() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_bind API. 


Related Information 


e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 
e Idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


e idap_set_rebind_proc() -- Sets the entry-point of a routine during the chasing of referrals. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_bind_s()--Perform an LDAP Bind Request 
(Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_bind_s ( 
LDAP *1d, 
const char *dn, 
const char *cred, 
int method) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_bind_s() function provide synchronous general authentication routines, where in principle an 
authentication method can be chosen. In this toolkit, method must be set to LDAP_AUTH_SIMPLE. 


The Idap_bind_s() function is used to authenticate a distinguished name (DN) to a directory server. When 
connecting to an LDAP V2 server, after a connection is made by using the Idap_open() API, an LDAP 
bind API must be called before any other LDAP APIs can be called for that connection. Binding the 
connection is not required for LDAP V3. 


Idap_bind_s() is synchronous request. 


Since this APIs is deprecated, ldap_simple_bind_sQ) should be used instead. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


dn 
(Input) The distinguished name of the entry to bind as. 


cred 


(Input) The credentials with which to authenticate. Arbitrary credentials can be passed using this 
parameter. In most cases, this is the user's password. 


method 


(Input) Selects the authentication method to use. Specify LDAP_AUTH_SIMPLE for simple 
authentication. Simple authentication is the only supported method. 


Note that use of the Idap_bind_s() APIs is deprecated. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_bind_s() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 
CPF3CF2 E_ Error(s) occurred during running of Idap_bind_s API. 


Related Information 


e Idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 
e Idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


e idap_set_rebind_proc() -- Sets the entry-point of a routine during the chasing of referrals. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_compare()--Perform an LDAP Compare 
Operation 


Syntax 


#include <ldap.h> 


int ldap_compare ( 
LDAP 
const char 
const char 
const char 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_compare() function is used to perform an LDAP compare operation. The API uses as input the 
distinguished name (DN) of the entry on which to perform the compare, and uses an attr and value (the 
attribute type and value to compare to those found in the entry). 


Binary values are not supported by this API. Use Idap_compare_ext() if binary values must be compared. 


Idap_compare() is an asynchronous request. The result of the operation can be obtained by a subsequent 


call to ldap_resultQ. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 


dn 
(Input) The DN of the entry upon which to perform the compare. 


attr 


(Input) The attribute type to use in the comparison. 


value 


(Input) The string attribute value to compare against the value in the entry. 


Return Value 


Message ID of the Operation Initiated 


if the request was successful. 


-1 


if the request was not successful. 


Error Conditions 


If Idap_compare() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_compare API. 


Related Information 


e |dap_compare_s() -- Synchronous compare to a directory entry. 


e |dap_compare_ext() -- Asynchronous compare to a directory entry with controls. 


e Idap_compare_ext_s(Q) -- Synchronous compare to a directory entry with controls. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_compare_ext()--Perform an LDAP 
Compare Operation with Controls 


Syntax 


#include <ldap.h> 


struct berval { 
unsigned long bv_len; 
char *bv_val; 


}; 


int ldap_compare_ext ( 
LDAP *ld, 
const char *dn, 
const char eater, 
const berval *bvalue, 
LDAPControl **serverctrils, 
LDAPControl **clientctrls, 
int *msgidp) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_compare_ext() function is used to perform an LDAP compare operation with controls. The 
Idap_compare_ext() API initiates an asynchronous compare operation and returns the constant 
LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


dn 
(Input The distinguished name (DN) of the entry upon which to perform the compare. 


attr 


(Input) The attribute type to use in the comparison. 


bvalue 


(Input) The attribute value to compare against the value in the entry. This is a pointer to a struct 
berval, making it possible to compare binary values. 


serverctrls 


(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 


clientctrls 


(Input) A list of LDAP client controls. This parameter may be set to null. See LDAP Controls for 
more information about client controls. 


msgidp 


(Output) This result parameter is set to the message ID of the request if the Idap_compare_ext() 
call succeeds. 


Return Value 


LDAP_SUCCESS 


if the request was successfully sent. If successful, lIdap_compare_ext() places the message ID of 
the request in *msgidp. A subsequent call to Idap_result() can be used to obtain the result of the 
operation. Once the operation has completed, Idap_result() returns a result that contains the status 


of the operation in the form of an error code. The error code indicates if the operation completed 
successful (LDAP_COMPARE_TRUE or LDAP_COMPARE_ FALSE). 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_compare_ext() API will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_compare_ext API. 


Related Information 


e idap_compare() -- Asynchronous compare to a directory entry. 


e Idap_compare_s() -- Synchronous compare to a directory entry. 


e Idap_compare_ext_s(Q) -- Synchronous compare to a directory entry with controls. 


The Idap_compare_ext() API supports LDAP V3 server controls and client controls. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_compare_ext_s()--Perform an LDAP 
Compare Operation with Controls 
(Synchronous) 


Syntax 


#include <ldap.h> 


struct berval { 
unsigned long bv_len; 
char *bv_val; 


}; 


int ldap_compare_ext_s ( 
LDAP *1d,; 
const char *dn, 
const char *attr, 
const berval *bvalue, 
LDAPControl **k serverctrls, 
LDAPControl *kxclientctrls) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_compare_ext_s() function is used to perform a synchronous LDAP compare operation with 
controls. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_init(), or ldap_openQ. 


dn 
(Input) The distinguished name (DN) of the entry upon which to perform the compare. 


attr 


(Input) The attribute type to use in the comparison. 
bvalue 


(Input) The attribute value to compare against the value in the entry. This is a pointer to a struct 
berval, making it possible to compare binary values. 


serverctrls 


(Input) A list of LDAP server controls. This parameter may be set to null. See LDAP Controls for 
more information about server controls. 


clientctrls 


(Input) A list of LDAP client controls. This parameter may be set to null. See LDAP Controls for 
more information about client controls. 


Return Value 


LDAP_COMPARE_TRUE 


if the entry contains the attribute value. 


LDAP_COMPARE_FALSE 


if the entry does not contain the attribute value. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_compare_ext_s() API will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_— Error(s) occurred during running of Idap_compare_ext_s API. 


Related Information 


e idap_compare() -- Asynchronous compare to a directory entry. 


e |dap_compare_s() -- Synchronous compare to a directory entry. 


e |dap_compare_ext() -- Asynchronous compare to a directory entry with controls. 


The Idap_compare_ext_s() API supports LDAP V3 server controls and client controls. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_compare_s()--Perform an LDAP Compare 
Operation (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_compare_s ( 
LDAP *ld, 
const char *dn, 
const char *attr, 
const char *value) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_compare_s() function is used to perform an LDAP compare operation. The API uses as input the 
distinguished name (DN) of the entry on which to perform the compare, and uses an attr and value (the 
attribute type and value to compare to those found in the entry). 


Binary values are not supported by this API. Use Idap_compare_ext_s() if binary values must be compared. 
Idap_compare_s() is a synchronous request. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 


dn 

(Input) The distinguished name (DN) of the entry upon which to perform the compare. 
attr 

(Input) The attribute type to use in the comparison. 
value 


(Input) The string attribute value to compare against the value in the entry. 


Return Value 


LDAP_COMPARE_TRUE 


if the entry contains the attribute value. 


LDAP_COMPARE_FALSE 


if the entry does not contain the attribute value. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_compare_s() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_compare_s API. 


Related Information 


e |dap_compare() -- Asynchronous compare to a directory entry. 


e idap_compare_ext() -- Asynchronous compare to a directory entry with controls. 


e Idap_compare_ext_s(Q) -- Synchronous compare to a directory entry with controls. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_controls_free()--Free storage allocated by 
the LDAP library 


Syntax 


#include <ldap.h> 


void ldap_controls_free(LDAPControl **ctrils) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_controls_free() routine is used to free storage allocated by the LDAP APIs that uses an array of 
LDAPControl structure. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


ctrls 


(Input) The address of an LDAPControl list, represented as a NULL-terminated array of pointers to 
LDAPControl structures. 


Return Value 


None. 


Error Conditions 


The Idap_controls_free() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 
Message ID _ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_controls_free API. 


Related Information 


e idap_ber_freeQ -- Free storage allocatd for BerElement structure. 
e |dap_memfree() -- Free storage that has been allocated by the LDAP client library. 
e lidap_control_freeQ -- Free a single LDAPControl structure. 


e |Idap_msgfree() -- Free LDAP Result Message. 


e Idap_mods_free() -- Free an array of pointers to mod structures. 


e Idap_parse_resultQ -- Extract Information from Results 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_control_free()--Free storage allocated by 
the LDAP library 


Syntax 


#include <ldap.h> 


void ldap_control_free(LDAPControl *ctrl) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_control_free() routine is used to free storage allocated by the LDAP APIs that uses an 
LDAPControl structure. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


ctrl 
(Input) The address of an LDAPControl structure. 


Return Value 


None. 


Error Conditions 


The Idap_control_free() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID _ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_control_free API. 


Related Information 


e Idap_controls_freeQ -- Free an array of LDAPControl structures. 


e |dap_parse_resultQ -- Extract Information from Results 


API introduced: V4R5 
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Idap_count_attributes()--Retrieve Count of 
Attributes for an LDAP Entry 


Syntax 


#include <ldap.h> 


int ldap_count_attributes ( 
LDAP *ld, 
LDAPMes sage *entry) 


Library Name/Service Program: QS YS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_attributes() function returns a count of the number of attributes in an LDAP entry. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


entry 
(Input) The attribute information as returned by Idap_first_entry( or ldap_next_entry(). 


Return Value 


Number of Attributes 


if the request was successful. 


-1 


if the request was not successful. 


Error Conditions 


The Idap_count_attributes() API returns -1 if a null entry is passed as input to Idap_count_attributes(). 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of Idap_count_attributes API. 


Related Information 


e idap_first_attribute( -- Return first attribute name in an entry. 


e idap_next_attribute( -- Return next attribute name in an entry. 


e idap_first_entryQ -- Retrieve First LDAP Entry 
e idap_next_entry(Q -- Retrieve Next LDAP Entry 


API Introduce: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_count_entries()--Retrieve Count of LDAP 
Entries 


Syntax 


#include <ldap.h> 


int ldap_count_entries ( 
LDAP *ld, 
LDAPMes sage *result) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_entries() API returns the number of entries contained in a search result chain. It can also 
be used to count the number of entries that remain in a chain if called with a message, entry or continuation 
reference returned by Idap_first_message(), Idap_next_message(), Idap_first_entry(), 
Idap_next_entry(), Idap_first_reference() or Idap_next_reference(), respectively. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


result 


(Input) The result returned by a call to Idap_result() or by one of synchronous search routines 
(idap_search_sQ or ldap_search_stQ). 


Return Value 


Number of Entries 


If the request is successful, Idap_count_entries() returns the number of entries contained in a 
search result chain. It can also be used to count the number of entries that remain in a chain if 
called with a message, entry or continuation reference. 


-1 


if the request was not successful. 


Error Conditions 


If Idap_count_entries() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use ldap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of ldap_count_entries API. 


Related Information 


e idap_first_entryQ -- Return first entry in a chain of search results. 


e idap_next_entry( -- Return next entry in a chain of search results. 


e idap_get_entry_controls_npQ -- Extract server controls from an entry. 


e idap_first_reference() -- Return first continuation reference in a chain of search results. 


e Idap_next_reference() -- Return next continuation reference in a chain of search results. 


e Idap_count_references() -- Return number of continuation reference in a chain of search results. 


e |Idap_parse_reference_npQ) -- Extract information from a continuation reference. 
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Top | Directory Services APIs | APIs by category 


Idap_count_messages()--Count messages in a 
result chain 


Syntax 


#include <ldap.h> 


int ldap_count_messages (LDAP *1d, 
LDAPMessage *result) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_messages() routine is used to step through the list of messages in a result chain, as 
returned by Idap_result(). It is used to count the number of messages returned. The ldap_msgtypeQ) API can 


be used to distinguish between the different message types. 
In addition to returning the number of messages contained in a chain of results, the Idap_count_messages() 
API can be used to count the number of messages that remain in a chain if called with a message, entry, or 


reference returned by Idap_first_message(), Idap_next_message(), Idap_first_entry(), 
Idap_next_entry(), Idap_first_reference() and Idap_next_reference(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 


result 


(Input) The result returned by a call to Idap_result() or one of the synchronous search routines 


(idap_search_s(Q), Idap_search_st(), or Idap_search_ext_st()). 


Return Value 


Number of Messages 


If the request was successful, Idap_count_messages() API retuns the number of messages in a 
result chain or number of messages that remain in a chain, as returned by Idap_result(). 


-1 


if the request was not successful. 


Error Conditions 


If Idap_count_messages() is not successful, /d_errno will be set to indicate the error. See LDAP Client 
API Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of Idap_count_messages API. 


Related Information 


e idap_first_message() -- Return first message in a result chain. 


e idap_next_message() -- Return next message in a result chain. 


API introduced: V4R5 
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Idap_count_references()--Count continuation 
references in a chain of search results 


Syntax 


#include <ldap.h> 


int ldap_count_references (LDAP *1ld, 
LDAPMessage *result) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_references() API is used to count the number of continuation references returned. It can 
also be used to count the number of continuation references that remain in a chain. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


result 


(Input) The result returned by a call to Idap_resultQ) or one of the synchronous search routines 
(idap_search_s(), ldap_search_st(Q), or Idap_search_ext_s()). 


Return Value 


Number of continuation reference 


If the request was successful, Idap_count_references() API returns the number of continuation 
references in a result chain or number of continuation references that remain in a chain, as returned 
by Idap_result(. 


-1 


if the request was not successful. 


Error Conditions 


If ldap_count_references() is not successful, /d_errno will be set to indicate the error. See LDAP Client 
API Error Conditions for possible LDAP error code values. Use ldap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of Idap_count_references API. 


Related Information 


e idap_first_reference() -- Return first continuation reference in a result chain, as returned by 
Idap_result. 


e idap_next_reference() -- Return next continuation reference in a result chain, as returned by 
Idap_result. 


API introduced: V4R5 
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Idap_count_values()--Retrieve Count of 
Attribute Values 


Syntax 


#include <ldap.h> 


int ldap_count_values ( 
char *xvals) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_values() function returns the number of values in the array returned by the 


Idap_get_values() function. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


vals 


(Input) A pointer to a null-terminated array of attribute values, as returned by ldap_get_values(). 


Return Value 


Number of Values 


if the request is successful, lIdap_count_values() returns the number of values in the array returned 
by the Idap_get_values() function. 


-1 


if the request was not successful. 


Error Conditions 


If ldap_count_values() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of Idap_count_values API. 


Related Information 


e Idap_get_values() -- Return an attribute's values. 


e idap_get_values_lenQ -- Return an attribute's binary values. 


e idap_count_values_lenQ -- Return number of binary values. 


e idap_value_free(Q) -- Free memory allocated by ldap_get_values. 


e idap_value_free_lenQ -- Free memory allocated by ldap_get_values_len. 


API introduced: V4R3 
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Idap_count_values_len()--Retrieve Count of 
Binary Attribute Values 


Syntax 


#include <ldap.h> 


struct berval { 
unsigned long bv_len; 
char *bv_val; 

}; 


int ldap_count_values_len ( 
struct berval **bvals) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_count_values_len() function returns the number of values in the array returned by the 
et_values_lenQ function. The array of values returned can be freed by calling Idap_value_free_lenQ. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


bvals 


(Input) A pointer to a null-terminated array of pointers to berval structures, as returned by 
Idap_get_values_lenQ. 


Return Value 


Number of Values 


if the request is successful, lIdap_count_values_len() returns the number of values in the array 
returned by the ldap_get_values_len() function. 


-l 


if the request was not successful. 


Error Conditions 


if ldap_count_values_len() is not successful, /d_errno will be set to indicate the error. See LDAP Client 
API Error Conditions for possible LDAP error code values. Use ldap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_count_values_len API. 


Related Information 


e idap_get_values() -- Return an attribute's values. 


e idap_get_values_lenQ -- Return an attribute's binary values. 


e |dap_count_values() -- Return number of values. 


e idap_value_freeQ) -- Free memory allocated by Idap_get_values(). 


e idap_value_free_lenQ -- Free memory allocated by Idap_get_values_len(). 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_default_dn_get()-- Retrieve the User's 
Default DN 


Syntax 


#include <ldap.h> 
int ldap_default_dn_get ( 


char **default_dn, 
char * filename) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_default_dn_get() API is used to retrieve the user's default DN. To free the returned string, use 


Idap_memfree(). 


An application stores the default DN on disk by calling ldap_default_dn_set(). For OS/400 the default file 


(used when filename is NULL) where the default DN stored is called Idap_user_info and will be found in 
the user's home directory. A user's home directory is specified in the user's profile. 


Authorities and Locks 


The caller must have Execute (*X) authority to each directory in the path name preceding the name of the 
user information file. The caller must have Read (*R) authority to the user information file. 


Parameters 


default_dn 


(output) Specifies the user's default Distinguished Name. Free *default_dn with ldap_memfree() 
when no longer needed. 


filename 


(Input) Specifies an alternative location for the user's default Distinguished Name storage. If only a 
filename is given for the filename parameter then the file will be checked in the current directory, 
otherwise, if a path is given as well as a filename as part of the filename parameter, the file will be 
checked following the given path. If filename is NULL, a file called lIdap_user_info in the user's 
home directory will be read. 


Return Value 


LDAP_SUCCESS 
if the default DN was retrieved. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_default_dn_get() API will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_default_dn_get API. 


Related Information 


e idap_default_dn_set() -- Store the User's Default DN. 
e Idap_enetwork_domain_set() -- Store the User's Default eNetwork Domain Name. 
e Idap_enetwork_domain_get( -- Retrieve the User's Default eNetwork Domain Name. 


e Idap_memfreeQ -- Free Memory Allocated by LDAP API 


API introduced: V4R5 
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Idap_default_dn_set()-- Store the User's Default 
DN 


Syntax 


#include <ldap.h> 
int ldap_default_dn_set ( 


char *default_dn, 
char * filename) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_default_dn_set() API is used to store the user's default DN. The DN can be obtained by calling 
Idap_default_dn_get(). 


The default DN is stored on disk. For OS/400 the default file the information will be stored in will be called 
Idap_user_info and will be put into the user's home directory. A user's home directory is specified in the 
user's profile. The home directory must be created prior to calling Idap_default_dn_set() and is not created 
as part of the creation of a user's profile. It will be stored in the local character set format. 


Authorities and Locks 


The caller must have Execute (*X) authority to each directory in the path name preceding the name of the 
user information file. The caller must have Write (*W) authority to the user information file. If the filename 
file doesn't exist in the directory when calling Idap_default_dn_set, the caller must have Write (*W) 
authority to the file's parent directory. 


Parameters 


default_dn 
(input) Specifies the user's default Distinguished Name. 
filename 


(Input) Specifies an alternative location for the user's default Distinguished Name storage. If only a 
filename is given for the filename parameter then a file will be created in the current directory, 
otherwise, if a path is given as well as a filename as part of the filename parameter, the file will be 
created following the given path. If filename is NULL, a file called Idap_user_info will be created 
into the user's home directory. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_default_dn_set() API will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of the ldap_default_dn_set API. 


Related Information 


e idap_default_dn_get() -- Retrieve the User's Default DN. 


e ldap _enetwork domain _set() -- Store the User's Default eNetwork Domain Name. 


e idap_enetwork_domain_get( -- Retrieve the User's Default eNetwork Domain Name. 


API introduced: V4R5 
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Idap_delete()--Perform an LDAP Delete 
Operation 


Syntax 


#include <ldap.h> 
int ldap_delete ( 


LDAP *ld, 
const char * dn) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_delete() routine initiates an asynchronous LDAP operation to delete a leaf entry. The result of the 
operation can be obtained by a subsequent call to Idap_result(). 


Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire 
subtrees in a single operation is not supported by LDAP. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

dn 
(Input) Specifies the DN of the entry to be deleted. 


Return Value 


Message ID of the Operation Initiated 
If the request was successful. 
-1 


If the request was not successful. 


Error Conditions 


If Idap_delete() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_delete API. 


Related Information 


e@ Idap_delete_sQ -- Synchronous delete an entry. 


e@ Idap_delete_ext(Q) -- Asynchronous delete an entry with controls. 


e Idap_delete_ext_sQ -- Synchronous delete an entry with controls. 
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Idap_delete_ext()--Perform an LDAP Delete 
Operation with Controls 


Syntax 


#include <ldap.h> 


int ldap_delete_ext (LDAP *ld, 
const char *dn, 
LDAPControl **serverctrls, 
LDAPControl *xclientctrls, 


int *msgidp) 
Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_delete_ext() routine initiates an asynchronous LDAP operation to delete a leaf entry with 
controls. 


Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire 
subtrees in a single operation is not supported by LDAP. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

dn 
(Input) Specifies the Distinguished Name (DN) of the entry to be deleted. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


msgidp 


(Output) This result parameter is set to the message id of the request if the Idap_delete_ext() call 
succeeds. 


Return Value 


LDAP_SUCCESS 


if the request was successfully sent, Idap_delete_ext() places the message id of the request in 
*msgidp. A subsequent call to ldap_resultQ can be used to obtain the result of the operation. Once 


the operation has completed, Idap_result() returns a result that contains the status of the operation 
(in the form of an error code). The error code indicates if the operation completed successfully. 


another LDAP error code 


if the request was not successfully. 


Error Conditions 


The Idap_delete_ext() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_delete_ext API. 


Related Information 


e Idap_deleteQ -- Asynchronous delete an entry. 
e@ Idap_delete_sQ -- Synchronous delete an entry. 


e Idap_delete_ext_sQ -- Synchronous delete an entry with controls. 
The Idap_delete_ext() API supports LDAP V3 server controls and client controls. 
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Idap_delete_ext_s()--Perform an LDAP Delete 
Operation with Controls 


Syntax 


#include <ldap.h> 


int ldap_delete_ext_s (LDAP *ld, 
const char *dn, 
LDAPControl **kserverctrls, 
LDAPControl *xclientctrls) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_delete_ext_s() routine initiates a synchronous LDAP operation to delete a leaf entry with 
controls. 


Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire 
subtrees in a single operation is not supported by LDAP. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

dn 
(Input) Specifies the Distinguished Name (DN) of the entry to be deleted. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_delete_ext_s() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_delete_ext_s API. 


Related Information 


e@ Idap_deleteQ -- Asynchronous delete an entry. 
e Idap_delete_sQ -- Synchronous delete an entry. 


e Idap_delete_extQ -- Asynchronous delete an entry with controls. 


The Idap_delete_ext_s() API supports LDAP V3 server controls and client controls. 
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Idap_delete_s()--Perform an LDAP Delete 
Operation (Synchronous) 


Syntax 


#include <ldap.h> 
int ldap_delete_s ( 


LDAP *1d, 
const char * dn) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_delete_s() routine initiates a synchronous LDAP operation to delete a leaf entry. 


Note that the entry to delete must be a leaf entry (that is, it must have no children). Deletion of entire 
subtrees in a single operation is not supported by LDAP. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 


dn 
(Input) Specifies the Distinguished Name (DN) of the entry to be deleted. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_delete_s() will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_delete_s API. 


Related Information 


e Idap_deleteQ -- Asynchronous delete an entry. 


e Idap_delete_ext(Q -- Asynchronous delete an entry with controls. 


e Idap_delete_ext_sQ -- Synchronous delete an entry with controls. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_dn2ufn()--Convert a Distinguished Name 
into a User Friendly Name 


Syntax 


#include <ldap.h> 


char *ldap_dn2ufn ( 
const char *dn) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_dn2ufn(Q) function takes a distinguished name (DN) and converts into a "friendlier" 
representation by removing the attribute type that is associated with each relative distinguished name 
(RDN). For example, the DN "cn=John Doe,ou=Widget Division,ou=Austin,o=IBM,c=US" would be 
returned in its "friendlier" form as "John Doe, Widget Division, Austin, IBM, US". Space for the 
user-friendly name will have been obtained by the API, and should be freed by the caller with a call to 


Idap_memfree(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


dn 
(Input) Specifies the DN to be converted (as returned from Idap_get_dnQ). 


Return Value 


Character String 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If Idap_dn2ufn(Q) is not successful, then there was no memory available for the character string. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_dn2ufn API. 


Related Information 


e |dap_get_dnQ -- Extract the DN from an entry. 


e Idap_explode_rdnQ -- Break a Relative Distinguished Name into Its Components. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_enetwork_domain_get()-- Retrieve the 
User's Default eNetwork Domain Name 


Syntax 


#include <ldap.h> 
int ldap_enetwork_domain_get ( 


char **xkedomain, 
char * filename) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_enetwork_domain_get() API is used to retrieve the user's default eNetwork domain name. To 
free the returned string, use ldap_memfree(). 


The eNetwork domain name (along with the user's default Domain Name Service (DNS) domain name) is 
used to identify the user's LDAP authentication domain. For example, if a user's eNetwork domain name is 
"chicago", and the user's DNS domain is midwest.illinois.com, then information can be published in DNS 
that associates Idap.chicago.midwest.illinois.com with a collection of LDAP servers (master(s) and 
replicas). This permits applications to easily find an appropriate LDAP authentication server, by using the 
Idap_server_locate() API. 


An application stores the eNetwork domain name on disk by calling ldap_enetwork_domain_set(). For 


OS/400 the default file where the eNetwork domain name stored is called Idap_user_info and will be 
found in the user's home directory. A user's home directory is specified in the user's profile. 


Authorities and Locks 


The caller must have Execute (*X) authority to each directory in the path name preceding the name of the 
user information file. The caller must have Read (*R) authority to the user information file. 


Parameters 


edomain 
(Output) Specifies the name of the eNetwork domain to which the user belongs. 
filename 


(Input) Specifies an alternative location for the user's default eNetwork domain name. If only a 
filename is given for the filename parameter then the file will be found in the current directory, 
otherwise, if a path is given as well as a filename as part of the filename parameter, the file will be 
found by following the given path. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_enetwork_domain_get() will return an LDAP error code if not successful. See LDAP Client 
API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_enetwork_domain_get API. 


Related Information 


e idap_default_dn_set() -- Store the User's Default DN. 


e idap_default_dn_get() -- Retrieve the User's Default DN. 


e Idap_enetwork_domain_set() -- Store the User's Default eNetwork Domain Name. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_enetwork_domain_set()-- Store the User's 
Default eNetwork Domain Name 


Syntax 


#include <ldap.h> 
int ldap_enetwork_domain_set ( 


char *edomain, 
char * filename) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_enetwork_domain_set() API is used to store the user's default eNetwork domain name 
(specified as a NULL terminated string). 


The eNetwork domain name (along with the user's default Domain Name Service (DNS) domain name) is 
used to identify the user's LDAP authentication domain. For example, if a user's eNetwork domain name is 
"chicago", and the user's DNS domain is midwest.illinois.com, then information can be published in DNS 
that associates Idap.chicago.midwest.illinois.com with a collection of LDAP servers (master(s) and 
replicas). This permits applications to easily find an appropriate LDAP authentication server, by using the 
Idap_server_locate() API. 


An application can retrieve the eNetwork domain name by calling ldap_enetwork_domain_get(). 


The eNetwork domain name is stored on disk. For OS/400 the default file the information will be stored in 
will be called Idap_user_info and will be put into the user's home directory. A user's home directory is 
specified in the user's profile. The home directory must be created prior to calling 
Idap_enetwork_domain_set() and is not created as part of the creation of a user's profile. It will be stored 
in the local character set format. 


Authorities and Locks 


The caller must have Execute (*X) authority to each directory in the path name preceding the name of the 
user information file. The caller must have Write (*W) authority to the user information file. If the file 
doesn't exist in the directory, the caller must have Write (*W) authority to the file's parent directory. 


Parameters 


edomain 
(Input) Specifies the name of the eNetwork domain to which the user belongs. 


filename 


(Input) Specifies an alternative location for the user's default eNetwork domain name. If only a 
filename is given for the filename parameter then a file will be created in the current directory, 
otherwise, if a path is given as well as a filename as part of the filename parameter, the file will be 
created following the given path. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_enetwork_domain_set() API will return an LDAP error code if not successful. See LDAP Client 
API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_enetwork_domain_set API. 


Related Information 


e Idap_default_dn_set( -- Store the User's Default DN. 
e idap_default_dn_get( -- Retrieve the User's Default DN. 


e Idap_enetwork domain_get() -- Retrieve the User's Default eNetwork Domain Name. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_err2string()--Retrieve LDAP Error 
Message String 


Syntax 


#include <ldap.h> 


char *ldap_err2string ( 
int error) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_err2string() function is used to retrieve the text description corresponding to an LDAP error 
code. 


The text description returned will be provided in English only. 


The string returned from Idap_err2string() should not be freed when use of the string is complete. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


error 


(Input) Specifies the LDAP error code returned by a previous call to ldap_result2errorQ, 
Idap_get_errnoQ, or a synchronous LDAP API. 


Return Value 


LDAP error description String 


a textual description of the LDAP error code. 


Error Conditions 


The Idap_err2string() API will return "Unknown Error" if the LDAP error code is unknown. See LDAP 
Client API Error Conditions for possible LDAP error codes and their description. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_err2string API. 


Related Information 


e |dap_get_errno( -- Retrieve Error Code set. 
e |dap_perror( -- Print an LDAP error indication to standard error. 
e |dap_result2error() -- Extract LDAP error indication from LDAP result. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_explode_dn()--Break a Distinguished 
Name into Its Components 


Syntax 


#include <ldap.h> 
char **ldap_explode_dn ( 


const char *dn, 
int notypes) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_explode_dn() function uses the distinguished name in local codepage returned by Idap_get_dnQ 


and breaks it up into its component parts. Each part is known as a Relative Distinguished Name (RDN). If 
the dn is in UTF8, use ldap_explode_dn_utf8Q). 


Idap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the 
DN. The notypes parameter is used to request that only the RDN values be returned, not their types. 


For example, the distinguished name cn=Bob,c=US would return as either "cn=Bob","c=US",NULL or 
"Bob","US", NULL depending on whether notypes was 0 or 1, respectively. The result can be freed by 
calling ldap_value_free(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


dn 
(Input) Specifies the DN to be exploded (as returned from Idap_get_dn(Q). 


notypes 
(Input) Specifies if type information is to be returned with each RDN. If non-zero, the type 
information will be stripped. If zero, the type information is retained. For example, setting notypes 
to 1 would result in the RDN "cn=Fido" being returned as "Fido". 


Return Value 


Relative Distinguished Name (RDN) 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If Idap_explode_dnQ) is not successful, then there was no memory available for either the array or its 
component parts. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_explode_dn API. 


Related Information 


e |dap_get_dnQ -- Extract the DN from an entry. 
e Idap_explode_dn_utf8Q -- Break a UTF8 Distinguided Name into its components. 


e idap_explode_rdnQ -- Break a Relative Distinguished Name into its components. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_explode_dns()--Break a DNS-style 
Distinguished Name into Its Components 


Syntax 


#include <ldap.h> 


char **ldap_explode_dns ( 
const char *dn) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_explode_dns() function takes a Domain Name System (DNS)-style distinguished name and 
breaks it up into its component parts. 


Idap_explode_dns() returns a NULL-terminated array of character strings. 


For example, the DNS-style distinguished name rochester.ibm.com would be returned as an array of 


Wome wow 


components "rochester","ibm","com",NULL. The result can be freed by calling ldap_value_freeQ. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


dn 
(Input) Specifies the DNS-style DN to be exploded. 


Return Value 


An array of character strings. 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If ldap_explode_dns() is not successful, no memory is available for the array or its components. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_explode_dns API. 


Related Information 


e idap_explode_dnQ -- Break a Distinguished Name into its components. 


e Idap_explode_dn_utf8Q -- Break a UTF8 codepage Distinguished Name into Its Components 


e idap_explode_rdnQ -- Break a Relative Distinguished Name into its components. 


e Idap_explode_rdn_utf8Q) -- Break a UTF8 codepage Relative Distinguished Name into Its 
Components 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_explode_dn_utf8()--Break a UTF8 
codepage Distinguished Name into Its 
Components 


Syntax 


#include <ldap.h> 
char **ldap_explode_dn_ut f8 ( 


char *dn, 
int notypes) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_explode_dn_utf8() function uses the distinguished name in UTF8 characters returned by 
Idap_get_dnQ and breaks it up into its component parts. Each part is known as a Relative Distinguished 


Name (RDN). If the dn is in local codepage, use ldap_explode_dnQ. 


Idap_explode_dn_utf8() returns a NULL-terminated array, each component of which contains an RDN 
from the DN. The notypes parameter is used to request that only the RDN values be returned, not their 


types. 


For example, the distinguished name cn=Bob,c=US would return as either "cn=Bob","c=US",NULL or 
"Bob","US", NULL depending on whether notypes was 0 or 1, respectively. The result can be freed by 
calling ldap_value_free(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


dn 
(Input) The DN to be exploded in UTF8 codepage (as returned from Idap_get_dn(). 


notypes 
(Input) Whether type information is to be returned with each RDN. If non-zero, the type 
information is stripped. If zero, the type information is retained. For example, setting notypes to 1 
would result in the RDN "cn=Fido" being returned as "Fido". 


Return Value 


Relative Distinguished Name (RDN) 


The request was successful. 


NULL 


The request was not successful. The ldap_get_errno() API can be used to obtain the error code. 


Error Conditions 


If ldap_explode_dn_utf8() is not successful, /d_errno is set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use the ldap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_explode_dn_utf8 API. 


Related Information 


e Idap_explode_dnQ -- Break a Distinguished Name into Its Components. 


e Idap_explode_rdnQ -- Break a Relative Distinguished Name into Its Components. 


e Idap_explode_rdn_utf8Q -- Break a UTF8 codepage Relative Distinguished Name into Its 
Components. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_explode_rdn()--Break a Relative 
Distinguished Name into Its Components 


Syntax 


#include <ldap.h> 


char **ldap_explode_rdn ( 
const char *rdn, 


int notypes) 


Default Public Authority: *USE 
Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_explode_rdn() function uses the relative distinguished name (RDN) in the local CCSID (as 
returned by Idap_explode_dnQ, for example) and breaks it up into its component parts. If the RDN is in 


UTF8, use Idap_explode_rdn_utf8Q. 


Idap_explode_rdn() returns a NULL-terminated array of character strings. The notypes parameter is used 
to request that only the component values be returned, not their types. 


For example, the RDN "ou=Research+cn=Bob" would return as either {"ou=Research", "cn=Bob", NULL} 
or {"Research","Bob", NULL}, depending on whether notypes was 0 or 1, respectively. The result can be 
freed by calling Idap_value_free(Q). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


rdn 


(Input) Specifies the RDN to be exploded (perhaps as returned by Ildap_explode_dnQ)). Multiple 
RDNs can be concatenated using a plus sign (‘+’). 


notypes 


(Input) Specifies if type information is to be returned with each RDN. If non-zero, the type 
information will be stripped. If zero, the type information is retained. For example, setting notypes 
to 1 would result in the RDN "cn=Fido" being returned as "Fido". 


Return Value 


Components of Relative Distinguished Name (RDN) 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If l\dap_explode_rdnQ) is not successful, then there was no memory available for either the array or its 
component parts. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_explode_rdn API. 


Related Information 


e Idap_explode_dnQ -- Break a Distinguished Name into its components. 


e Idap_explode_rdn_utf8Q -- Break a UTF8 Relative Distinguished Name into its components. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_explode_rdn_utf8()--Break a UTF8 
codepage Relative Distinguished Name into Its 
Components 


Syntax 


#include <ldap.h> 
char **ldap_explode_rdn_utf8 ( 


char *rdn, 
int notypes) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_explode_rdn_utf8() function uses the relative distinguished name (RDN) in UTF8 characters (as 
returned by, Idap_explode_dn_utf8Q, for example) and breaks it up into its component parts. If the RDN is 


in local codepage, use Idap_explode_rdnQ). 


Idap_explode_rdn_utf8() returns a NULL-terminated array of character strings. The notypes parameter is 
used to request that only the component values be returned, not their types. 


For example, the RDN "ou=Research+cn=Bob" would return as either {"ou=Research", "cn=Bob", NULL} 
or {"Research","Bob", NULL}, depending on whether notypes was 0 or 1, respectively. The result can be 
freed by calling Idap_value_free(Q). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


rdn 


(Input) The RDN to be exploded (perhaps as returned by Idap_explode_dn_utf8Q). Multiple RDNs 
can be concatenated using a plus sign (‘+’). 


notypes 
(Input) Whether type information is to be returned with each RDN. If non-zero, the type 
information is stripped. If zero, the type information is retained. For example, setting notypes to 1 
would result in the RDN "cn=Fido" being returned as "Fido". 


Return Value 


Components of Relative Distinguished Name (RDN) 


The request was successful. 


NULL 
The request was not successful. The ldap_get_errno() API can be used to obtain the error code. 


Error Conditions 


If ldap_explode_rdn_utf8() is not successful, /d_errno will be set to indicate the error. See LDAP Client 
API Error Conditions for possible LDAP error code values. Use the ldap_get_errno() function to retrieve 
the error information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_explode_rdn_utf8 API. 


Related Information 


e Idap_explode_dnQ -- Break a Distinguished Name into Its Components. 
e Idap_explode_dn_utf8Q -- Break a UTF8 codepage Distinguished Name into Its Components. 


e Idap_explode_rdnQ -- Break a Distinguished Name into Its Components. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_extended_operation()--Perform extended 
operations. 


Syntax 


#include <ldap.h> 


int ldap_extended_operation ( 
LDAP e100, 
const char * regoid, 
const struct berval *reqdata, 
LDAPControl **k serverctrls, 
LDAPControl *kclientctrls, 
int *msgidp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_extended_operation() function is used to initiate an asynchronous extended operation, which 
returns LDAP_SUCCESS if the extended operation was successfully sent, or an LDAP error code if not. If 
successful, the Idap_extended_operation() API places the message id of the request in *msgid. A 
subsequent call to Idap_resultQ can be used to obtain the result of the extended operation, which can then 
be passed to ldap_parse_extended_result() to obtain the Object [Dentifier (OID) and data contained in the 


response. 


If the LDAP server does not support the extended operation, the server will reject the request. To determine 
if the requisite extended operation is supported by the server, get the rootDSE of the LDAP server, and 
check for the supportedExtension attribute. If the values for this attribute include the OID of your extended 
operation, then the server supports the extended operation. If the supportedExtension attribute is not present 
in the rootDSE, then the server is not configured to support any extended operations. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


reqoid 
(Input) Specifies the dotted-OID text string that identifies the extended operation to be performed 


by the server. 
reqdata 


(Input) Specifies the arbitrary data required by the extended operation (if NULL, no data is sent to 
the server). 


serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 

msgidp 


(Output) This result parameter is set to the message id of the request if the 
Idap_extended_operation() call succeeds. 


Return Value 


LDAP_SUCCESS 


if the request was successful. Idap_extended_operation() places the message id of the request in 
*msgidp. To check the result of this operation, call Idap_result() and Idap_parse_extended_resultQ 


APIs. The server may also return an OID and result data. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_extended_operation() is not successful, will return a -1 instead of a valid msgid, setting the 
session error in the LD structure, which can be obtained by using Idap_get_errno(Q). 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_extended_operation API. 


Related Information 


e Idap_add_ext() -- Asynchronously add an entry with controls. 


e@ Idap_add_ext_s() -- Synchronously add an entry with controls. 


e idap_compare_ext() -- Asynchronous compare to a directory entry with controls. 


e Idap_compare_ext_s(Q) -- Synchronous compare to a directory entry with controls. 


e@ Idap_delete_ext(Q -- Asynchronous delete an entry with controls. 


e Idap_delete_ext_sQ -- Synchronous delete an entry with controls. 


e Idap_modify_extQ -- Asynchronously modify an entry with controls. 


e idap_modify_ext_sQ -- Synchronously modify an entry with controls. 


e Idap_parse_extended_resultQ -- Parse extended result. 


e idap_sasl_bindQ -- Asynchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 

e idap_sasl_bind_sQ -- Synchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 

e Idap_search_ext() -- Asynchronously search the directory with controls. 


e idap_search_ext_s() -- Synchronously search the directory with controls. 
e idap_rename() -- Asynchronously rename an entry with controls. 


e Idap_rename_sQ -- Synchronously rename an entry with controls. 


e Idap_unbind_extQ -- Unbind with controls. 
The Idap_extended_operation() API supports LDAP V3 server controls and client controls. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_extended_operation_s()--Perform 
extended operations synchronously 


Syntax 


#include <ldap.h> 


int ldap_extended_operation_s ( 
LDAP *1ld, 
const char * regqoid, 
const struct berval *reqdata, 
LDAPControl **serverctrls, 
LDAPControl *kclientctrls, 
char *x retoidp, 
struct berval ** retdatap) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_extended_operation_s() function is used to perform a synchronous LDAP extended operation, 
which returns LDAP_SUCCESS if the extended operation completed successfully, or an LDAP error code 
if not. The retoid and retdata parameters are filled in with the Object [Dentifier (OID) and data from the 
response. If no OID or data was returned, these parameters are set to NULL, respectively. 


If the LDAP server does not support the extended operation, the operation will fail. To determine if the 
requisite extended operation is supported by the server, get the rootDSE of the LDAP server and check for 
the supportedExtension attribute. If the values for this attribute include the object identifier of your 
extended operation, then the server supports the extended operation. If the supportedExtension attribute is 
not present in the rootDSE, then the server is not configured to support any extended operations. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 


reqoid 


(Input) Specifies the dotted-OID text string that identifies the extended operation to be performed 
by the server. 


reqdata 


(Input) Specifies the arbitrary data required by the extended operation (if NULL, no data is sent to 
the server). 


serverctrls 


(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 


clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


retoidp 


(Output) This result parameter is set to point to a character string that is set to an allocated, 
dotted-OID text string returned from the server. This string should be disposed of using the 
Idap_memfree() API. If no OID is returned, *retoidp is set to NULL. 


retdatap 


(Output) This result parameter is set to a pointer to a berval structure pointer that is set to an 
allocated copy of the data returned by the server. This struct berval should be disposed of using 
ber_bvfree(). If no data is returned, *retdatp is set to NULL. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_extended_operation_s() is not successful, it will return the LDAP error code resulting from the 
operation. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of Idap_extended_operation_s API. 


Related Information 


Idap_add_extQ -- Asynchronously add an entry with controls. 


Idap_add_ext_sQ) -- Synchronously add an entry with controls. 


ldap_compare_ext() -- Asynchronous compare to a directory entry with controls. 


Idap_compare_ext_s() -- Synchronous compare to a directory entry with controls. 


Idap_delete_extQ) -- Asynchronous delete an entry with controls. 


Idap_delete_ext_sQ -- Synchronous delete an entry with controls. 


Idap_modify_extQ -- Asynchronously modify an entry with controls. 


Idap_modify_ext_s() -- Synchronously modify an entry with controls. 


Idap_sasl_bindQ -- Asynchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 

Idap_sasl_bind_sQ) -- Synchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 


Idap_search_extQ) -- Asynchronously search the directory with controls. 


Idap_search_ext_s() -- Synchronously search the directory with controls. 


Idap_rename() -- Asynchronously rename an entry with controls. 


Idap_rename_sQ) -- Synchronously rename an entry with controls. 


Idap_unbind_extQ -- Unbind with controls. 


The Idap_extended_operation_s() API supports LDAP V3 server controls and client controls. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_first_attribute()--Retrieve First Attribute in 
an Entry 


Syntax 


#include <ldap.h> 


char *ldap_first_attribute ( 
LDAP *ld, 
LDAPMessage *entry, 
BerElement **berptr) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_first_attribute() function returns the first attribute in an entry. The Idap_first_attributeQ) and 
Idap_next_attributeQ functions are used to step through the attributes in an LDAP entry. 


Idap_first_attribute() takes an entry returned by Idap_first_entry(Q or Idap_next_entry( and returns a 


pointer to a buffer containing a null terminated string that is the first attribute type in the entry. This buffer 
must be freed when its use is completed using Idap_memfree(). *berptr also must be freed when its use is 


completed using Idap_ber_free(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) The LDAP pointer returned by a previous call to Idap_initQ, ldap_ssl_initQ, 
Idap_app_ssl_init_npQ, or Idap_openQ. 


entry 
(Input) The attribute information as returned by Idap_first_entryQ or ldap_next_entry(Q. 


berptr 


(Output) A pointer to a BerElement that will be allocated to keep track of the current position. It is 
an input and output parameter for subsequent calls to Idap_next_attributeQ. The BerElement 


structure is opaque to the application. Free *berptr when its use is completed using ber_free. 


Return Value 


Pointer to a buffer containing the first attribute type in the entry 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If Idap_first_attribute() is not successful, NULL is returned, and /d_errno will be set to indicate the error. 
See LDAP Client API Error Conditions for possible LDAP error code values. Use Idap_get_errnoQ) 


function to retrieve the error information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_first_attribute API. 


Related Information 


e Idap_first_entry( -- Retrieve first LDAP entry. 


e idap_next_entry( -- Retrieve next LDAP entry. 


e idap_count_attributes() -- Retrieve count of attributes for an LDAP entry. 


e idap_next_attribute( -- Return next attribute name in an entry. 


e lidap_get_values( -- Retrieve a set of attribute values from an entry. 


e Idap_get_values_lenQ -- Retrieve a set of binary attribute values. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_first_entry()--Retrieve First LDAP Entry 


Syntax 


#include <ldap.h> 
LDAPMessage *ldap_first_entry ( 


LDAP *Id, 
LDAPMessage *result) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_first_entry() function takes the result from a call to Idap_result(), Idap_search_s(), or 
ldap_search_stQ and returns a pointer to the first entry in the result. 


The Idap_first_entry(), ldap_next_entry(), and Idap_count_entries() functions are used to parse results 
received from Idap_resultQ or the synchronous LDAP search functions Idap_search_s() and 
Idap_search_st(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


result 


(Input) The result returned by a call to Idap_resultQ) or one of the synchronous search routines 
(idap_search_sQ or ldap_search_st(Q). 


Return Value 


Pointer to the next entry in the result 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If ldap_first_entry() is not successful, NULL is returned, /d_errno will be set to indicate the error. See 
LDAP Client API Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to 


retrieve the error information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_first_entry API. 


Related Information 


e idap_next_entry( -- Return next entry in a chain of search results. 


e idap_count_entries(Q -- Return number of entries in a chain of search results. 


e idap_get_entry_controls_npQ -- Extract server controls from an entry. 


e lIdap_first_reference( -- Return first continuation reference in a chain of search results. 


e idap_next_reference() -- Return next continuation reference in a chain of search results. 


e |dap_count_references() -- Return number of continuation reference in a chain of search results. 


e idap_parse_reference_npQ) -- Extract information from a continuation reference. 


e idap_first_message -- Retrieve first LDAP message. 


e idap_next_message() -- Retrieve next LDAP message. 
e idap_msgfreeQ -- Free LDAP result message. 
e idap_msgtypeQ -- Retrieve Type of an LDAP Message 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_first_message()--Retrieve First LDAP 
Message 


Syntax 


#include <ldap.h> 


LDAPMessage *ldap_first_message (LDAP *ld, 
LDAPMes sage *result) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_first_message() routine is used to step through the list of messages in a result chain, as returned 
by Idap_resultQ. It is used to return a pointer to the first message in the list. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ , or 
Idap_open(). 


result 


(Input) The result returned by a call to Idap_resultQ or one of the synchronous search routines 
(idap_search_s(), ldap_search_st(Q), or lIdap_search_ext_s()). 


Return Value 


LDAPMessage * 


Pointer to the first message. 


NULL 


when no message exists in the result set or if an error occurs. 


Error Conditions 


If Idap_first_message() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_first_message API. 


Related Information 


e idap_count_messages() -- Return the number of message in a result chain. 


e ldap_first_entry() -- Retrieve first LDAP entry. 


e idap_first_reference( -- Return first continuation reference in a chain of search results. 
e idap_msgfreeQ -- Free LDAP result message. 

e idap_msgidQ -- Retrieve message ID associated with an LDAP message. 

e idap_msgtypeQ -- Retrieve type of an LDAP message. 


e idap_next_message() -- Retrieve next LDAP message. 


e |dap_result2error() -- Retrieve LDAP error information 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_first_reference()--Retrieve First 
Continuation Reference in a Chain of Search 
Results 


Syntax 


#include <ldap.h> 


LDAPMessage *ldap_first_reference (LDAP 4160; 
LDAPMes sage *result) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_first_reference() is used to return the first continuation reference from the search result chain. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ), or ldap_openQ. 


result 


(Input) The result returned by a call to Idap_resultQ) or one of the synchronous search routines 
(idap_search_sQ), ldap_search_stQ, or ldap_search_ext_s()). 


Return Value 


LDAPMessage * 


Pointer to the first continuation reference. The pointer returned from Idap_first_reference() should 
be supplied on a subsequent call to lIdap_next_reference() to get the next continuation reference. 


NULL 


when no more continuation references exist in the result set to be returned. 


Error Conditions 


If ldap_first_reference() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 
Message ID Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_first_reference API. 


Related Information 


e idap_first_entry( -- Return first entry in a chain of search results. 


e Idap_next_entry( -- Return next entry in a chain of search results. 


e Idap_count_entry( -- Return number of entry in a chain of search results. 


e |dap_get_entry_controls_np() -- Extract server controls from an entry. 


e |dap_count_reference() -- Return the number of continuation reference in a chain of search results. 


e |dap_next_reference() -- Return next continuation reference in a chain of search results. 


e idap_parse_reference_npQ) -- Extract information from a continuation reference. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_free_urldesc()--Free an LDAP URL 
Description 


Syntax 


#include <ldap.h> 


typedef struct ldap_url_desc { 
char *lud_host; LDAP host to contact */ 
int lud_port; port on host */ 
char *lud_dn; base for search */ 
char **]lud_attrs; NULL-terminate list of attributes */ 
int lud_scope; a valid LDAP_SCOPE_... value */ 
char *lud_filter; LDAP search filter */ 
char *lud_string; for internal use only */ 
} LDAPURLDesc; 


void ldap_free_urldesc ( 
LDAPURLDesc *ludp) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_free_urldesc() function is called to free an LDAP URL description that was obtained from a call 


to the Idap_url_parseQ) function. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


ludp 
(Input) Points to the LDAP URL description, as returned by ldap_url_parse(). 


Return Value 


None. 


Error Conditions 


The Idap_free_urldesc() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 
Message ID _ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_free_urldesc API. 


Related Information 


e Idap_is_Idap_urlQ -- Check a URL string to see if it is an LDAP URL. 
e idap_url_parse() -- Break up an LDAP URL string into its components. 
e Idap_url_searchQ -- Asynchronously search using an LDAP URL. 


e idap_url_search_sQ -- Synchronously search using an LDAP URL. 
e idap_url_search_stQ -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_get_dn()--Retrieve the Distinguished 
Name of an Entry 


Syntax 


#include <ldap.h> 
char *ldap_get_dn ( 


LDAP *ld, 
LDAPMessage *entry) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_get_dn() function takes an entry as returned by Idap_first_entry( or ldap_next_entry() and 


returns a copy of the entry's Distinguished Name (DN). Memory for the DN will have been allocated and 
should be freed by a call to ldap_memfree(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(),ldap_ssl_initQ, or 


Idap_open(). 


entry 


(Input) The entry whose dn is to be retrieved, as returned by Specifies the LDAP pointer returned 
by a previous call to Idap_first_entryQ or Idap_next_entry(. 


Return Value 


Copy of the entry's DN 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If Idap_get_dnQ) is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_get_dn API. 


Related Information 


e |dap_explode_dnQ -- Convert a DN into its component parts. 


e Idap_explode_dn_utf8Q -- Break a UTF8 codepage Distinguished Name into its components 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_get_entry_controls_np()--Extract Server 


Controls from an Entry 


Syntax 


#include <ldap.h> 


int ldap_get_entry_controls_np ( 
LDAP 
LDAPMessage 
LDAPControl 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


*1ld, 
*entry, 
*** serverctrilsp) 


The Idap_get_entry_controls_np() routine is used to retrieve an array of server controls returned in an 


individual entry in a chain of search results. 


Note the suffix "_np" which shows the API is in a preliminary implementation, and is not documented in 


the Internet Draft. The Internet community may standardize this API in the future. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ), or 


Idap_open(). 


entry 


(Input) Specifies a pointer to an entry returned on a previous call to Idap_first_entryQ or 


Idap_next_entry(). 


serverctrisp 


(Input) Specifies a pointer to a result parameter that is filled in with an allocated array of controls 


copied out of the entry. The control array should be freed by calling ldap_controls_free(). 


Return Value 


LDAP_SUCCESS 


if the call was successful 


another LDAP error code 


if the call was not successful. 


Error Conditions 


The Idap_get_entry_controls_np() API will return LDAP error code if not successful. See LDAP Client 
API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_get_entry_controls_np API. 


Related Information 


e idap_first_entry( -- Return first entry in a chain of search results. 


e idap_next_entry( -- Return next entry in a chain of search results. 


e idap_count_entry( -- Return the number of entry in a chain of search results. 


e idap_first_reference() -- Return first continuation reference in a chain of search results. 


e |dap_next_reference() -- Return next continuation reference in a chain of search results. 


e |dap_count_references() -- Return number of continuation reference in a chain of search results. 


e idap_parse_reference_npQ -- Extract information from a continuation reference. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_get_errno()--Retrieve Error Information 


Syntax 


#include <ldap.h> 


int ldap_get_errno ( 
LDAP * 1d) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_get_errno() function retrieves information about the most recent error that occurred for an LDAP 
operation. This function can be called for any LDAP API that does not return an error. 


The Idap_get_lderrno() API returns more error information than Idap_get_errno(. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


Return Value 


LDAP error code 
See LDAP Client API Error Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of ldap_get_errno API. 


Related Information 


e Idap_err2string( -- Convert LDAP error indication to a string. 
e |dap_get_Iderrno() -- Retrieve Error Information. 


e |dap_perror( -- Print an LDAP error indication to standard error. 


e ldap_result2errorQ -- Extract LDAP error indication from LDAP result. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_get_iconv_local_ codepage()-- Get the 
Active LDAP Code Page 


Syntax 


#include <ldap.h> 


char * 
ldap_get_iconv_local_codepage ( ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: No 


The Idap_get_iconv_local_codepage() API is used to obtain the active LDAP code page. It returns the 


value of a global variable /dap_global_codepage set by ldap_set_iconv_local_codepage(). To free the 
returned string, use ldap_memfree(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


No parameter are passed to Idap_get_iconv_local_codepage(). 


Return Value 


LDAP Code page 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If Idap_get_iconv_local_codepage() is not successful, it returns NULL. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_get_iconv_local_codepage API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert String From the Local to UTF-8 Code Page. 


e Idap_xlate_utf8_to_localQ -- Convert String From UTF-8 to Local Code Page. 


e Idap_xlate_local_to_unicode() -- Convert String From the Local to UCS-2 Code Page. 


e Idap_xlate_unicode_to_local() -- Convert String From UCS-2 to Local Code Page. 


e Idap_set_iconv_local_codepage() -- Set the Active LDAP Code Page. 
e Idap_set_iconv_local_charset() -- Set the Active LDAP Character set. 
e Idap_set_locale() -- Change the Locale Used by LDAP. 

e Idap_get_localeQ -- Get the Locale Used by LDAP. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_get_lIderrno()--Retrieve Error Information 


Syntax 


#include <ldap.h> 


int ldap_get_lderrno ( 
LDAP *Td; 
char ** dn, 
char **xerrmsg) 


Library Name/Service Program: QS YS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_get_Iderrno() function retrieves information about the most recent error that occurred for an 
LDAP operation. This function can be called for any LDAP API that does not return an error. 


When an error occurs at the LDAP server, the server returns both an LDAP result code and a message 
containing any additional information about the error from the server. If the error occurred because an entry 
specified by a Distinguished Name (DN) could not be found, the server may also return the portion of the 
DN that identifies an existing entry. Use ldap_get_Iderrno() to obtain both the message containing error 
information and the matched DN. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

dn 
(Output) The distinguished name (DN) that identifies an existing entry, indicating how much of the 
name in the request was recongnized by the server. The DN is returned when an 
LDAP_NO_SUCH_OBJECT error is returned from the server on some previous operation. The 
matched DN string should be freed by calling ldap_memfree(). 

errmsg 


(Output) The text of the error message, as returned from the server. The error message string should 
be freed by calling Idap_memfree(). 


Return Value 


LDAP error code 
See LDAP Client API Error Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_get_Iderrno API. 


Related Information 


e idap_err2string( -- Convert LDAP error indication to a string. 

e |dap_get_errno( -- Obtain information from most recent error. 

e |dap_perror( -- Print an LDAP error indication to standard error. 

e |dap_result2error() -- Extract LDAP error indication from LDAP result. 


e@ Idap_set_Iderrno(Q -- Set Error Information 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_get_locale()-- Get Active LDAP Locale 


Syntax 


#include <ldap.h> 


char *ldap_get_locale( ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: No 


The Idap_get_locale() API is used to obtain the active LDAP locale. To free the returned string, use 


Idap_memfree(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


No parameters are passed to Idap_get_locale() 


Return Value 


Active LDAP Locale 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


If ldap_get_locale() is not successful, it returns NULL. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_get_locale API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert String From the Local to UTF-8 Code Page. 


e Idap_xlate_utf8_to_local(Q -- Convert String From UTF-8 to Local Code Page. 
e Idap_xlate_local_to_unicode() -- Convert String From the Local to UCS-2 Code Page. 
e Idap_xlate_unicode_to_local(Q) -- Convert String From UCS-2 to Local Code Page. 


e Idap_get_iconv_local_codepage() -- Get the Active LDAP Code Page. 


e Idap_set_iconv_local_codepage() -- Set the Active LDAP Code Page. 


e Idap_set_iconv_local_charset() -- Set the Active LDAP Character set. 
e idap_set_localeQ -- Change the Locale Used by LDAP. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_get_option()--Retrieve LDAP Options 


Syntax 


#include <ldap.h> 


int ldap_get_option ( 
LDAP *ld, 
int optionToGet, 
void *optionValue) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_get_option() function is used to query settings associated with the specified LDAP connection. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


ld 


(Input) The LDAP pointer returned by a previous call to Idap_initQ), ldap_ssl_initQ, or ldap_openQ. 
If a NULL 1d is passed in, the default value for the option is retrieved. 


optionToGet 


(Input) The option value that is to be queried on the Idap_get_option() call. See below for the list 
of supported options. 


optionValue 
(Input) The address of the storage in which to return the queried value using Idap_get_option(). 
The following session settings can be get using the Idap_get_option() API: 


LDAP_OPT_SIZELIMIT maximum number of entries that can be returned on a search 
operation 


LDAP_OPT_TIMELIMIT maximum number of seconds to wait for search results. 


LDAP_OPT_REFHOPLIMIT 


LDAP_OPT_DEREF 
LDAP_OPT_REFERRALS 
LDAP_OPT_DEBUG 
LDAP_OPT_SSL_CIPHER 
LDAP_OPT_SSL_TIMEOUT 
LDAP_OPT_REBIND_FN 
LDAP_OPT_PROTOCOL_VERSION 
LDAP_OPT_SERVER_CONTROLS 
LDAP_OPT_CLIENT_CONTROLS 
LDAP_OPT_UTF8_IO 


LDAP_OPT_HOST_NAME 
LDAP_OPT_ERROR_NUMBER 
LDAP_OPT_ERROR_STRING 
LDAP_OPT_EXT_ERROR 
LDAP_OPT_EXT_GSS_ERR 


maximum number of referrals in a sequence that the client can 
follow 


rules for following aliases at the server. 

whether or not referrals should be followed by the client. 
debug options. 

SSL ciphers to use. 

SSL timeout for refreshing session keys 

address of application's setrebindproc procedure. 

LDAP protocol version to use (V2 or V3). 

default server controls. 

default client library controls. 


mode for converting string data between the local code page 
and UTF-8 


current host name 
error number 

error string 
extended error code 


GSSAPI extended error code 


Additional details on specific options for Idap_get_option() are provided in the following sections. 


LDAP_OPT_SIZELIMIT 


Specifies the maximum number of entries that can be returned on a search operation. Note: the actual size 
limit for operations is also bounded by the maximum number of entries that the server is configured to 
return. Thus, the actual size limit will be the lesser of the value specified on this option and the value 
configured in the LDAP server. The default sizelimit is unlimited, specified with a value of zero (thus 
deferring to the sizelimit setting of the LDAP server). 


Examples: 


sizevalue=50; 


ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue) ; 
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue ); 


LDAP_OPT_TIMELIMIT 


Specifies the number of seconds to wait for search results. Note: the actual time limit for operations is also 
bounded by the maximum time that the server is configured to allow. Thus, the actual time limit will be the 
lesser of the value specified on this option and the value configured in the LDAP server. The default is 
unlimited (specified with a value of zero). 


Examples: 


timevalue=50; 
ldap_set_option( ld, LDAP_OPT_TIMELIMIT, &timevalue) ; 
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, &timevalue ); 


LDAP_OPT_REFHOPLIMIT 


Specifies the maximum number of hops that the client library will take when chasing referrals. The default 
is 5. 


Examples: 


hoplimit=7; 
ldap_set_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit); 
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit) ; 


LDAP_OPT_DEREF 


Specifies alternative rules for following aliases at the server. The default is LDAP_DEREF_NEVER. 


Supported values: 
LDAP_DEREF_NEVER 0 
LDAP_DEREF_SEARCHING 1 
LDAP_DEREF_FINDING 2 
LDAP_DEREF_ALWAYS 3 


Examples: 


int deref = LDAP_DEREF_NEVER; 
ldap_set_option( ld, LDAP_OPT_DEREF, é&deref) ; 
ldap_get_option( ld, LDAP_OPT_DEREF, é&deref) ; 


LDAP_OPT_REFERRALS 


Specifies whether the LDAP library will automatically follow referrals returned by LDAP servers or not. It 
can be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. By default, the LDAP client 
will follow referrals. 


Examples: 


int value; 
ldap_set_option( ld, LDAP_OPT_REFFERALS, (void *)LDAP_OPT_ON); 
ldap_get_option( ld, LDAP_OPT_REFFERALS, &value); 


LDAP_OPT_DEBUG 


Specifies a bit-map that indicates the level of debug trace for the LDAP library. 

Supported values: 
LDAP_DEBUG_OFF 0x000 
LDAP_DEBUG_TRACE 0x001 
LDAP_DEBUG_PACKETS  0x002 
LDAP_DEBUG_ARGS 0x004 
LDAP_DEBUG_CONNS 0x008 
LDAP_DEBUG_BER 0x010 
LDAP_DEBUG_FILTER 0x020 
LDAP_DEBUG_CONFIG —_ 0x040 
LDAP_DEBUG_ACL 0x080 
LDAP_DEBUG_STATS 0x100 
LDAP_DEBUG_STATS2 0x200 
LDAP_DEBUG_SHELL 0x400 
LDAP_DEBUG_PARSE 0x800 


LDAP_DEBUG_ANY Oxffff 


Examples: 


int value; 

int debugvalue= LDAP_DEBUG_TRACE | LDAP _DEBUG_ PACKETS; 
ldap_set_option( ld, LDAP_OPT_DEBUG, &debugvalue) ; 
ldap_get_option( ld, LDAP_OPT_DEBUG, &value ); 


LDAP_OPT SSL_CIPHER 


Specifies a set of one or more ciphers to be used when negotiating the cipher algorithm with the LDAP 
server. The first cipher in the list that is common with the list of ciphers supported by the server is chosen. 
For the export version of the library, the value used is "0306". For the domestic version of the library, the 
default value is "05040A090306". Note that the cipher string supported by the export version of the LDAP 
client library is fixed and cannot be modified. 


Supported ciphers: 


LDAP_SSL_RC4_MD5_EX 03 


LDAP_SSL_RC2_MD5_EX 06 


LDAP_SSL_RC4_SHA_US — 05 (Non-export only) 


LDAP_SSL_RC4_MD5_US 04 (Non-export only) 


LDAP_SSL_DES_SHA_US 09 (Non-export only) 


LDAP_SSL_3DES_SHA_US 0A (Non-export only) 


Bs 2F (Non-export only)*& 
LDAP_SSL_AES_SHA_US 


Examples: 


char *setcipher = "2F090A"; 

char *getcipher; 

ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher) ; 
ldap_get_option( ld, LDAP_OPT_SSL_CIPHER, &getcipher ); 


Use Idap_memfree() to free the memory returned by the call to Idap_get_option(). 


LDAP_OPT_SSL_TIMEOUT 


Specifies in seconds the SSL inactivity timer. After the specified seconds, in which no SSL activity has 
occurred, the SSL connection will be refreshed with new session keys. A smaller value may help increase 
security, but will have a small impact on performance. The default SSL timeout value is 43200 seconds. 


Examples: 


value = 100; 
ldap_set_option( ld, LDAP_OPT_SSL_TIMEOUT, &value ); 
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &value) 


LDAP_OPT_REBIND_FN 


Specifies the address of a routine to be called by the LDAP library when the need arises to authenticate a 
connection with another LDAP server. This can occur, for example, when the LDAP library is chasing a 
referral. If a routine is not defined, referrals will always be chased using the anonymous identity. A default 
routine is not defined. 


Examples: 


extern LDAPRebindProc proc_address; 

LDAPRebindProc value; 

ldap_set_option( ld, LDAP_OPT_REBIND_FN, &proc_address) ; 
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &value); 


LDAP_OPT_PROTOCOL_VERSION 


Specifies the LDAP protocol to be used by the LDAP client library when connecting to an LDAP server. 
Also used to determine which LDAP protocol is being used for the connection. For an application that uses 
ldap_init(Q) to create the LDAP connection the default value of this option will be LDAP_VERSION3 for 
communicating with the LDAP server. The default value of this option will be LDAP_VERSION2 if the 
application uses the deprecated Idap_open() API. In either case, the 
LDAP_OPT_PROTOCOL_VERSION option can be used with Idap_set_option() to change the default. 
The LDAP protocol version should be reset prior to issuing the bind (or any operation that causes an 
implicit bind). 


Examples: 


version2 = LDAP_VERSION2; 

version3 = LDAP_VERSION3; 

/* Example for Version 3 application setting version to version 2 */ 
ldap_set_option( 1d, LDAP_OPT_PROTOCOL_VERSION, &version2); 

/* Example of Version 2 application setting version to version 3 */ 
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, é&version3); 
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, é&value) ; 


The value returned by Idap_get_optionQ) when LDAP_OPT_PROTOCOL_VERSION is specified can 
be used to determine how parameters should be passed to the ldap_set_option() call. The easiest way to 


work with this compatibility feature is to guarantee that calls to ldap_set_optionQ are all performed while 


LDAP_OPT_PROTOCOL_VERSION is set to the same value. If this cannot be guaranteed by the 
application, then follow the format of the example below when coding the call to Idap_set_option(Q: 


Examples: 


int sizeLimit=100; 

int protocolVersion; 

ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &protocolVersion ); 
if ( protocolVersion == LDAP_VERSION2 ) { 

ldap_set_option( ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit ); 


} else { /* the protocol version is LDAP_VERSION3 */ 
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizeLimit ); 


LDAP_OPT_SERVER_CONTROLS 


Specifies a default list of server controls to be sent with each request. The default list can be overridden by 
specifying a server control, or list of server controls, on specific APIs. By default, there are no settings for 
Server Controls. 


Example: 


ldap_set_option( ld, LDAP_OPT_SERVER_CONTROLS, é&ctrlp)j; 


LDAP_OPT_CLIENT_CONTROLS 


Specifies a default list of client controls to be processed by the client library with each request. Since client 
controls are not defined for this version of the library, the ldap_set_option() API can be used to define a set 
of default, non-critical client controls. If one or more client controls in the set is critical, the entire list is 
rejected with a return code of LDAP_UNA VAILABLE_CRITICAL_EXTENSION. 


LDAP_OPT_UTF8 _ IO 


Specifies whether the LDAP library will automatically convert string data to and from the local code page. 
It can be set to one of the constants LDAP_UTF8_XLATE_ON or LDAP_UTF8_XLATE_OFF. By 
default, the LDAP library will convert string data. 


When conversion is disabled, the LDAP library assumes that data received from the application by LDAP 
APIs is already represented in UTF-8. Similarly, the LDAP library assumes that the application is prepared 
to receive string data from the LDAP library represented in UTF-8 (or as binary). 


When LDAP_UTF8_XLATE_ON is set (the default), the LDAP library assumes that string data received 
from the application by LDAP APIs is in the default (or explicitly designated) code page. Similarly, all 
string data returned from the LDAP library (back to the application) is converted to the designated local 
code page. 


Notes: 


1. Only string data supplied on connection-based APIs will be translated (that is, only those APIs that 
include an Id will be subject to translation). 


2. Translation of strings from a UTF-8 encoding to local code page may result in loss of data when 
one or more characters in the UTF-8 encoding cannot be represented in the local code page. When 
this occurs, a substitution character replaces any UTF-8 characters that cannot be converted to the 
local code page. 


Example: 


int value; 
ldap_get_option( ld, LDAP_OPT_UTF8_I0O, é&value); 


LDAP_OPT HOST NAME 


This is a read-only option that returns a pointer to the hostname for the original connection (as specified on 


Idap_initQ), Idap_openQ, or Idap_ssl_initQ). 


Example: 


char *hostname; 
ldap_get_option( ld, LDAP_OPT_HOST_NAME, &hostname) ; 


Use ldap_memfree() to free the memory returned by the call to lIdap_get_option(). 


LDAP_OPT ERROR_NUMBER 


This is a read-only option that returns the error code associated with the most recent LDAP error that 
occurred for the specified LDAP connection. 


Example: 


int error; 
ldap_get_option( ld, LDAP_OPT_ERROR_NUMBER, &error); 


LDAP_OPT_ERROR_STRING 


This is a read-only option that returns the text message associated with the most recent LDAP error that 
occurred for the specified LDAP connection. 


Example: 


char *error_string; 
ldap_get_option( 1d, LDAP_OPT_ERROR_STRING, &error_string) ; 


Use ldap_memfree() to free memory returned by the call to Idap_get_option(). 


LDAP_OPT EXT ERROR 


This is a read-only option that returns the extended error code. For example, if an SSL error occurred when 
attempting to call an ldap_search_s() API, the actual SSL error can be obtained by using 


LDAP_OPT_EXT_ERROR. 


Example: 


int exterror; 
ldap_get_option( ld, LDAP_OPT_EXT_ERROR, &exterror); 


Returns errors reported by the SSL library. 


LDAP_OPT EXT GSS ERR 


This is a read-only option that returns the extended error code from SASL binds using the GSSAPI 
mechanism. 


Example: 


int gsserror; 
ldap_get_option( ld, LDAP_OPT_EXT_GSS_ERR, &gsserror); 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_get_option() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible values for LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_get_option API. 


Related Information 


e Idap_init() -- Initializes a session with an LDAP server. 
e Idap_set_option() -- Set an option associated with an LDAP descriptor. 
e idap_version(Q -- Obtain LDAP version and SSL cipher information. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_get_values()--Retrieve a Set of Attribute 
Values from an Entry 


Syntax 


#include <ldap.h> 


char **ldap_get_values ( 
LDAP * 1d, 
LDAPMessage *entry, 
const char *attr) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_get_values() function is used to retrieve attribute values from an LDAP entry as returned by 
Idap_first_entryQ or ldap_next_entry(). Idap_get_values() uses the entry and the attribute attr whose values 
are wanted and returns a NULL-terminated array of the attribute's values. The returned array should be 
freed with ldap_value_freeQ when it is no longer needed. 


Use Idap_get_values_lenQ) to get binary attribute values. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

entry 
(Input) Specifies an LDAP entry as returned from ldap_first_entryQ or Idap_next_entryQ. 

attr 


(Input) Specifies the attribute whose values are desired. 


Return Value 


Array of Values 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


The Idap_get_values() API will return NULL and set the /d_errno error code, if not successful. See LDAP 
Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_get_values API. 


Related Information 


e Idap_get_values_lenQ -- Return an attribute's binary values. 


e ldap _count_values() -- Return number of values. 


e Idap_count_values_lenQ -- Return number of binary values. 


e Idap_value_free(Q) -- Free memory allocated by Ildap_get_values(). 


e Idap_value_free_lenQ -- Free memory allocated by Idap_get_values_len(). 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_get_values_ len()--Retrieve a Set of Binary 
Attribute Values 


Syntax 


#include <ldap.h> 


struct berval { 
unsigned long bv_len; 
char *bv_val; 


be 


struct berval **ldap_get_values_1len ( 
LDAP *ld, 
LDAPMessage *entry, 
const char *attr) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_get_values_len() function is used to retrieve attribute values that are binary in nature from an 


LDAP entry as returned by Idap_first_entryQ or ldap_next_entry(). 


The Idap_get_values_len() API uses the same parameters as Idap_get_values(), but returns a 


NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a 
value. Use Idap_value_free_len() to free the returned attribute values when they are no longer needed. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

entry 
(Input) Specifies an LDAP entry as returned from ldap_first_entryQ or Idap_next_entryQ. 

attr 


(Input) Specifies the attribute whose values are desired. 


Return Value 


NULL-terminated array of pointers to berval structures 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


The Idap_get_values_len() API will return NULL and set the /d_errno error code if not successful. See 
LDAP Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_get_values_len API. 


Related Information 


e |dap_get_valuesQ -- Return an attribute's values. 


e |dap_count_values() -- Return number of values. 


e idap_count_values_lenQ -- Return number of binary values. 


Idap_value_free() -- Free memory allocated by Idap_get_values(). 


e Idap_value_free_lenQ -- Free memory allocated by Idap_get_values_len(). 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_init()--Perform an LDAP Initialization Operation 


Syntax 


#include <ldap.h> 
LDAP *ldap_init ( 


char *host, 
int port) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_init() API is used to allocate an LDAP structure, which is used to identify the connection and to maintain 
per-connection information. 


The Idap_init() API returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP 
functions such as Idap_bind() and Idap_search(). 


Idap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that 
requires it, allowing various options to be set after initialization, but before actually contacting the host. It allocates an LDAP 


structure which is used to identify the connection and maintain per-connection information. Although still supported, the use 
of ldap_open() is deprecated. Use of Idap_init() instead of ldap_openQ is recommended. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


host 


(Input) Several methods are supported for specifying one or more target LDAP servers, including the following: 


Explicit Specifies the name of the host on which the LDAP server is running. The host parameter may contain a 
Host List blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If 
present, the -port overrides the port parameter. 


The following are typical examples: 


ld=ldap_init ("serverl1", ldap_port); 
ld=ldap_init ("server2:1200", ldap_port); 
ld=ldap_init ("serverl:800 server2:2000 server3", ldap_port); 


Localhost Tf the host parameter is NULL, the LDAP server will be assumed to be running on the local host. 


Default If the host parameter is set to LDAP_URL_PREFIX ("Idap://") the LDAP library will attempt to locate 
Hosts one or more default LDAP servers, with non-SSL ports, using the SecureWay Idap_server_locate() 


function. The port specified on the call is ignored, since Idap_server_locate() returns the port. 


For example, the following two are equivalent: 


ld=ldap_init ("ldap://", ldap_port); 
ld=ldap_init (LDAP_URL_PREFIX, LDAP_PORT) ; 


If more than one default server is located, the list is processed in sequence, until an active server is found. 


The LDAP URL can include a Distinguished Name (DN), used as a filter for selecting candidate LDAP 
servers based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact 
match with a server's suffix (after normalizing for case), the server is added to the list of candidate 
servers. For example, the following will only return default LDAP servers that have a suffix that supports 
the specified DN: 


ld=ldap_init ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT) ; 


In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one 
default server is located, the list is processed in sequence, until an active server is found. 


If the LDAP URL contains a host name and optional port, the host is used to create the connection. No 
attempt is made to locate the default server(s), and the DN, if present, is ignored. 


For example, the following two are equivalent: 


ld=ldap_init ("ldap://myserver", LDAP_PORT) ; 
ld=ldap_init ("myserver", LDAP_PORT); 


Local If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX socket 

Socket (that is, socket family is AF_UNIX) and port is ignored. Use of a UNIX socket requires the LDAP server 
to be running on the local host. In addition, the LDAP server must be listening on the specified UNIX 
socket. The OS/400 Secureway Directory Services server listens on the /tmp/s.slapd local socket, in 
addition to any configured TCP/IP ports. 


For example: 


ld=ldap_init ("/tmp/s.slapd", ldap_port); 


Host with Tf a specified host is prefixed with "privport://", then the LDAP library will use the rresvport() function to 

Privileged attempt to obtain one of the reserved ports (512 through 1023), instead of an "ephemeral" port. The search 

Port for a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call 
will fail. 


For example: 


ld=ldap_init ("privport://serverl,ldap_port"); 

ld=ldap_init ("privport://server2:1200", ldap_port) ; 

ld=ldap_init ("privport://server1:800 server2:2000 privport://server3", 
ldap_port); 


port 


Specifies the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT 
should be specified. 


Return Value 


Pointer to an LDAP structure 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


The Idap_init() API will return NULL if not successful. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_init API. 


Related Information 


e@ ldap_openQ -- Open a connection to an LDAP server (deprecated). 

e Idap_ssl_init( -- Initializes an SSL Connection 

e ldap_set_option( -- Set an option associated with an LDAP descriptor. 
e ldap_get_option( -- Get an option associated with an LDAP descriptor. 


e Idap_version( -- Obtain LDAP version and SSL cipher information. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_is Idap_url()--Verify LDAP URL 


Syntax 


#include <ldap.h> 


int ldap_is_ldap_url ( 
char ‘*url) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_is_Idap_url() function is used to check a string to verify if it could be an LDAP URL. It can be 
used as a quick check for an LDAP URL. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


url 


(Input) Specifies a pointer to the URL string. 


Return Value 


NON-ZERO 
if url begins with "Idap://" or "Idaps://". 


ZERO 
if not LDAP URL. 


Error Conditions 


The Idap_is_Idap_url() API return a ZERO if the input string (url) does not begin with "Idap://" or 
"Idaps://". 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_is_ldap_url API. 


Related Information 


e Idap_free_urldesc() -- Frees an LDAP URL description. 
e Idap_url_parse() -- Break up an LDAP URL string into its components. 
e Idap_url_searchQ -- Asynchronously search using an LDAP URL. 


e Idap_url_search_sQ -- Synchronously search using an LDAP URL. 


e Idap_url_search_st() -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_memfree()--Free Memory Allocated by 
LDAP API 


Syntax 


#include <ldap.h> 


void ldap_memfree ( 
char *mem) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_memfree() API is used to free storage that is allocated by some of the LDAP APIs. Refer to the 
specific LDAP API documentation to see which memory free API to use for any memory allocated. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


mem 


(Input) Specifies the address of storage that was allocated by the LDAP library. 


Return Value 


NONE 


Error Conditions 


The Idap_memfree() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_memfree API. 


Related Information 


e idap_ber_free(Q) -- Free the BerElement structure. 

e idap_ control _free() -- Free a single LDAPControl structure. 

e idap_controls_freeQ -- Free an array of LDAPControl structures. 
e |dap_free_urldesc -- Free an LDAP URL Description 


e idap_mods_free(Q -- Free an array of pointers to mod structures. 


e idap_msgfreeQ -- Free the LDAPMessage structure. 


e idap_server_free_list -- Free the List of LDAP Servers 


e idap_value_free -- Free memory allocated by Idap_get_values 
e Idap_value_free_len -- Free Memory Allocated by Idap_get_values_len 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_modify()--Perform an LDAP Modify Entry 
Request 


Syntax 


#include <ldap.h> 


typedef struct ldapmod { 
int mod_op; 
char *mod_type; 
union { 
char **modv_strvals; 
struct berval **modv_bvals; 
} mod_vals; 
} LDAPMod; 


#define mod_values mod_vals.modv_strvals 
#define mod_bvalues mod_vals.modv_bvals 


int ldap_modify ( 
LDAP 1d, 
const char *dn, 
LDAPMod **x mods) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modify() API is an asynchronous request. The result of the operation can be obtained by a 
subsequent call to Idap_result(). 


The mod_op field is used to specify the type of modification to perform and should be one of the following: 
LDAP_MOD_ADD 0x00 
LDAP_MOD_DELETE 0x01 
LDAP_MOD_REPLACE 0x02 


This field also indicates the type of values included in the mod_vals union. For binary data, you must also 
bitwise OR the operation type with LDAP_MOD_BVALUES (0x80). This indicates that the values are 
specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values will be used 
(that is, the values are assumed to be a NULL-terminated array of NULL-terminated character strings). 


The mod_type field specifies the name of attribute to add, delete, or replace. 


The mod_vals field specifies a pointer to a NULL-terminated array of values to add, modify or delete 
respectively. Only one of the mod_values or mod_bvalues variants should be used, with mod_bvalues being 


selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a 
NULL-terminated array of NULL-terminated strings and mod_bvalues is a NULL-terminated array of 
berval structures that can be used to pass binary values such as images. 


For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if 
necessary. 


For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the 
attribute if no values remain. If the entire attribute is to be deleted, the mod_values field should be set to 
NULL. The server will return an error if the attribute doesn't exist. 


For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the 
modification, having been created if necessary, or removed if the mod_values field is NULL. The server 
will NOT return an error if the value doesn't exist. 


All modifications are performed in the order in which they are listed. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

dn 
(Input) Specifies the Distinguished Name (DN) of the entry to be modified. 

mods 


(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of 
the mods array is a pointer to an LDAPMod structure. 


Return Value 


Message ID of the Operation Initiated 


if the request was successful. A subsequent call to Idap_resultQ), can be used to obtain the result of 
the modify. 


-l 


if the request was not successful. 


Error Conditions 


If ldap_modify() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_modify API. 


Related Information 


e Idap_addQ -- Asynchronously add an entry. 
e Idap_deleteQ -- Perform an LDAP Delete Operation. 


e idap_modify_sQ -- Synchronous modify to a directory entry. 


e Idap_modify_ext() -- Asynchronous modify to a directory entry with controls. 


e Idap_modify_ext_sQ -- Synchronous modify to a directory entry with controls. 


e idap_modrdnQ -- Asynchronously modify the RDN of an entry. 


e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_modify_ext()--Perform an LDAP Modify 
Entry Request with Controls 


Syntax 


#include <ldap.h> 


typedef struct ldapmod { 
int mod_op; 
char *mod_type; 
union { 
char **modv_strvals; 
struct berval **modv_bvals; 
} mod_vals; 
} LDAPMod; 


#define mod_values mod_vals.modv_strvals 
#define mod_bvalues mod_vals.modv_bvals 


int ldap_modify_ext ( LDAP *ld, 
const char *dn, 
LDAPMod **kmods, 
LDAPControl **k serverctrls, 
LDAPControl k*kclientctrls, 
int *xmsgidp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modify_ext() routine initiates an asynchronous modify operation with controls. dn is the 
Distinguished name of the entry to modify, and mods is a NULL-terminated array of modifications to make 
to the entry. Each element of the mods array is a pointer to an LDAPMod structure. 


The mod_op field is used to specify the type of modification to perform and should be one of the following: 
LDAP_MOD_ADD 0x00 
LDAP_MOD_DELETE 0x01 
LDAP_MOD_REPLACE 0x02 


This field also indicates the type of values included in the mod_vals union. For binary data, you must also 
bitwise OR the operation type with LDAP_MOD_BVALUES (0x80). This indicates that the values are 
specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values will be used 
(that is, the values are assumed to be a NULL-terminated array of NULL-terminated character strings). 


The mod_type field specifies the name of attribute to add, delete, or replace. 


The mod_vals field specifies a pointer to a NULL-terminated array of values to add, replace, or delete. Only 
one of the mod_values or mod_bvalues variants should be used, with mod_bvalues being selected by 
ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a NULL-terminated 
array of NULL-terminated strings and mod_bvalues is a NULL-terminated array of berval structures that 
can be used to pass binary values such as images. 


For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if 
necessary. 


For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the 
attribute if no values remain. If the entire attribute is to be deleted, the mod_values field should be set to 
NULL. The server will return an error if the attribute doesn't exist. 


For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the 
modification, having been created if necessary, or removed if the mod_vals field is NULL. The server 
should NOT return an error if the value doesn't exist. 


All modifications are performed in the order in which they are listed. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

dn 
(Input) Specifies the Distinguished Name of the entry to be modified. 

mods 
(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of 
the mods array is a pointer to an LDAPMod structure. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to NULL. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to NULL. See LDAP 
Controls for more information about client controls. 

msgidp 


(output) This result parameter is set to the message id of the request if the Idap_modify_ext() call 
succeeds. 


Return Value 


LDAP_SUCCESS 
if the request was successfully sent. If successful, Idap_modify_ext() places the message id of the 
request in *msgidp. A subsequent call to Idap_result() can be used to obtain the result of the 


operation. Once the operation has completed, /dap_result() returns a result that contains the status 
of the operation (in the form of an error code). The error code indicates whether or not the 
operation completed successfully. The Idap_parse_resultQ) API is used to check the error code in 


the result. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_modify_ext() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_modify_ext API. 


Related Information 


e@ Idap_add_ext() -- Asynchronously add an entry with controls. 

e@ Idap_delete_extQ) -- Perform an LDAP delete operation with controls. 
e idap_modifyQ -- Asynchronous modify to a directory entry. 

e idap_modify_sQ -- Synchronous modify to a directory entry. 


e Idap_modify_ext_sQ -- Synchronous modify to a directory entry with controls. 


e idap_modrdnQ -- Asynchronously modify the RDN of an entry. 


e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry. 


The Idap_modify_ext() API supports LDAP V3 server controls and client controls. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_modify_ext_s()--Perform an LDAP Modify 
Entry Request with Controls 


Syntax 


#include <ldap.h> 


typedef struct ldapmod { 
int mod_op; 
char *mod_type; 
union { 
char **modv_strvals; 
struct berval **modv_bvals; 
} mod_vals; 
} LDAPMod; 


#define mod_values mod_vals.modv_strvals 
#define mod_bvalues mod_vals.modv_bvals 


int ldap_modify_ext_s ( 
LDAP *1d; 
const char *dn, 
LDAPMod *xxmods, 
LDAPControl *kserverctrls, 
LDAPControl *kclientctrls) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modify_ext_s() API initiates a synchronous modify operation with controls. dn is the 
Distinguished name of the entry to modify, and mods is a NULL-terminated array of modifications to make 
to the entry. Each element of the mods array is a pointer to an LDAPMod structure. 


The mod_op field is used to specify the type of modification to perform and should be one of the following: 
LDAP_MOD_ADD 0x00 
LDAP_MOD_DELETE 0x01 
LDAP_MOD_REPLACE 0x02 


This field also indicates the type of values included in the mod_vals union. For binary data, you must also 
bitwise OR the operation type with LDAP_MOD_BVALUES (0x80). This indicates that the values are 
specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values will be used 
(that is, the values are assumed to be a NULL-terminated array of NULL-terminated character strings). 


The mod_type field specifies the name of attribute to add, delete, or replace. 


The mod_vals field specifies a pointer to a NULL-terminated array of values to add, modify or delete 
respectively. Only one of the mod_values or mod_bvalues variants should be used, with mod_bvalues being 
selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a 
NULL-terminated array of NULL-terminated strings and mod_bvalues is a NULL-terminated array of 
berval structures that can be used to pass binary values such as images. 


For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if 
necessary. 


For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the 
attribute if no values remain. If the entire attribute is to be deleted, the mod_values field should be set to 
NULL. The server will return an error if the attribute doesn't exist. 


For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the 
modification, having been created if necessary, or removed if the mod_values field is NULL. The server 
will NOT return an error if the value doesn't exist. 


All modifications are performed in the order in which they are listed. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

dn 
(Input) Specifies the Distinguished Name of the entry to be modified. 

mods 
(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of 
the mods array is a pointer to an LDAPMod structure. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


Return Value 


LDAP_SUCCESS 


if the request was successfully sent. 


LDAP error code 


if the request was not successfully sent. 


Error Conditions 


The Idap_modify_ext_sQ) will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_modify_ext_s API. 


Related Information 


e@ Idap_add_ext_s() -- Synchronously add an entry with controls. 
e Idap_delete_ext_sQ -- Perform an LDAP Delete Operation with Controls (Synchronous) 
e idap_modifyQ -- Asynchronous modify to a directory entry. 


e idap_modify_sQ -- Synchronous modify to a directory entry. 


e idap_modify_ext() -- Asynchronous modify to a directory entry with controls. 
e Idap_modrdnQ -- Asynchronously modify the RDN of an entry. 
e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_modify_s()--Perform an LDAP Modify 
Entry Request (Synchronous) 


Syntax 


#include <ldap.h> 


typedef struct ldapmod { 
int mod_op; 
char *mod_type; 
union { 
char **modv_strvals; 
struct berval **modv_bvals; 
} mod_vals; 
} LDAPMod; 


#define mod_values mod_vals.modv_strvals 
#define mod_bvalues mod_vals.modv_bvals 


int ldap_modify_s ( 
LDAP kh, 
const char *dn, 
LDAPMod ** mods) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modify_s() performs a synchronous request. 

The mod_op field is used to specify the type of modification to perform and should be one of the following: 
LDAP_MOD_ADD 0x00 
LDAP_MOD_DELETE 0x01 
LDAP_MOD_REPLACE 0x02 


This field also indicates the type of values included in the mod_vals union. For binary data, you must also 
bitwise OR the operation type with LDAP_MOD_BVALUES (0x80). This indicates that the values are 
specified in a NULL-terminated array of struct berval structures. Otherwise, the mod_values will be used 
(that is, the values are assumed to be a NULL-terminated array of NULL-terminated character strings). 


The mod_type field specifies the name of attribute to add, delete, or replace. 


The mod_vals field specifies a pointer to a NULL-terminated array of values to add, modify or delete 


respectively. Only one of the mod_values or mod_bvalues variants should be used, with mod_bvalues being 
selected by ORing the mod_op field with the constant LDAP_MOD_BVALUES. mod_values is a 
NULL-terminated array of NULL-terminated strings and mod_bvalues is a NULL-terminated array of 
berval structures that can be used to pass binary values such as images. 


For LDAP_MOD_ADD modifications, the given values are added to the entry, creating the attribute if 
necessary. 


For LDAP_MOD_DELETE modifications, the given values are deleted from the entry, removing the 
attribute if no values remain. If the entire attribute is to be deleted, the mod_values field should be set to 
NULL. The server will return an error if the attribute doesn't exist. 


For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the 
modification, having been created if necessary, or removed if the mod_values field is NULL. The server 
will NOT return an error if the value doesn't exist. 


All modifications are performed in the order in which they are listed. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(),ldap_ssl_initQ, or 
Idap_open(). 

dn 
(Input) Specifies the Distinguished Name of the entry to be modified. 

mods 


(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of 
the mods array is a pointer to an LDAPMod structure. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


The Idap_modify_s() API will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_modify_s API. 


Related Information 


e@ Idap_add_s() -- Perform an LDAP add operation (synchronous). 
e idap_delete_sQ -- Perform an LDAP delete operation (synchronous). 
e idap_modifyQ -- Perform an LDAP modify entry request. 


e idap_modify_ext() -- Asynchronous modify to a directory entry with controls. 


e Idap_modify_ext_sQ -- Synchronous modify to a directory entry with controls. 


e idap_modrdnQ -- Asynchronously modify the RDN of an entry. 


e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_modrdn()--Perform an LDAP Modify RDN 
Request 


Syntax 


#include <ldap.h> 


int ldap_modrdn ( 
LDAP *1ld, 
const char *dn, 
const char *newrdn, 
int deleteoldrdn) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modrdn() function is used to perform an LDAP modify relative distinguished name (RDN) 
operation. The function takes the distinguished name of the entry whose RDN is to be changed, and 
newrdn, the new RDN to give the entry. The deleteoldrdn parameter is used as a boolean value to indicate 
whether the old RDN values should be deleted from the entry or not. 


Idap_modrdn() performs an asynchronous request. The result of the operation can be obtained by a 
subsequent call to Idap_result(). 


In LDAP V2, the Idap_modrdn() and Idap_modrdn_s() APIs were used to change the name of an LDAP 


entry. They could only be used to change the least significant component of a name (the RDN or relative 
distinguished name). LDAP V3 provides the Modify DN protocol operation that allows more general name 
change access. The ldap_rename() and Idap_rename_s() routines are used to change the name of an entry, 


and the use of the Idap_modrdn() and ldap_modrdn_s(Q) routines are deprecated. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 
(Input) Specifies the DN of the entry whose RDN is to be changed. 


newrdn 


(Input) Specifies the new RDN to be given to the entry. 


deleteoldrdn 


(Input) Specifies a boolean value. When set to 1, the old RDN value is to be deleted from the entry. 
When set to 0, the old RDN value should be retained as a non-distinguished value. 


Return Value 


Message ID of the Operation Initiated 


if the request was successful. A subsequent call to Idap_result(), can be used to obtain the result of 
the modify. 


if 


if the request was not successful. 


Error Conditions 


If ldap_modrdn() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible LDAP error code values. Use the Idap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_modrdn API. 


Related Information 


e Idap_addQ -- Perform an LDAP add operation. 

e idap_deleteQ -- Perform an LDAP delete operation. 

e idap_modifyQ -- Asynchronous modify to a directory entry. 

e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry. 


e@ |dap_rename() -- Asynchronously rename an entry. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_modrdn_s()--Perform an LDAP Modify 
RDN Request (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_modrdn_s ( 
LDAP *1d, 
const char *dn, 
const char *newrdn, 


int deleteoldrdn) 


Default Public Authority: *USE 
Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_modrdn_s() function is used to perform an LDAP modify relative distinguished name (RDN) 
operation. The function takes the distinguished name of the entry whose RDN is to be changed, and 
newrdn, the new RDN to give the entry. The deleteoldrdn parameter is used as a boolean value to indicate 
whether the old RDN values should be deleted from the entry or not. 


Idap_modrdn_s() performs a synchronous request. 


In LDAP V2, the Idap_modrdn() and ldap_modrdn_s() APIs were used to change the name of an LDAP 


entry. They could only be used to change the least significant component of a name (the RDN or relative 
distinguished name). LDAP V3 provides the Modify DN protocol operation that allows more general name 
change access. The ldap_rename() and Idap_rename_s() routines are used to change the name of an entry, 


and the use of the Idap_modrdn() and ldap_modrdn_s(Q) routines are deprecated. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 
(Input) Specifies the DN of the entry whose RDN is to be changed. 


newrdn 


(Input) Specifies the new RDN to be given to the entry. 


deleteoldrdn 


(Input) Specifies a boolean value. When set to 1, the old RDN value is to be deleted from the entry. 
When set to 0, the old RDN value should be retained as a non-distinguished value. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


The Idap_modrdn_s() will return an LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_modrdn_s API. 


Related Information 


e Idap_addQ -- Perform an LDAP add operation. 

e Idap_delete(Q -- Perform an LDAP delete operation. 

e idap_modifyQ -- Asynchronous modify to a directory entry. 

e Idap_modrdnQ -- Asynchronously modify the RDN of an entry. 


e idap_rename_sQ) -- Synchronously rename an entry. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_mods_free()--Free LDAP Modify Storage 


Syntax 


#include <ldap.h> 


void ldap_mods_free ( 
LDAPMod **mods, 
int freemods) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_mods_free() function is used to free storage associated with the ldap_modify() and related LDAP 
APIs. 


Idap_mods_free() can be used to free each element of a NULL-terminated array of modification structures. 
If freemods is nonzero, the mods pointer itself is freed, otherwise freeing mods is left to the caller. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


mods 


(Input) Specifies a NULL-terminated array of modifications to make to the entry. Each element of 
the mods array is a pointer to an LDAPMod structure. 


freemods 


(Input) Specifies whether or not the mods pointer is to be freed in addition to the NULL-terminated 
array of LDAPMod structures. 


Return Value 


None 


Error Conditions 


The Idap_mods_free() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_mods_free API. 


Related Information 


e ldap_ber_free( -- Free the BerElement structure. 


e idap_control_freeQ -- Free a single LDAPControl structure. 


e idap_controls_free() -- Free an array of LDAPControl structures. 


e idap_free_urldesc -- Free an LDAP URL Description 


e idap_mods_free() -- Free an array of pointers to mod structures. 

e idap_memfreeQ -- Free storage allocated by the LDAP client library. 
e Idap_modifyQ -- Perform an LDAP modify entry request. 

e idap_msgfreeQ -- Free the LDAPMessage structure. 

e Idap_server_free_list -- Free the List of LDAP Servers 


e Idap_value_free -- Free memory allocated by Idap_get_values 
e idap_value_free_len -- Free Memory Allocated by ldap_get_values_len 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_msgfree()--Free LDAP Result Message 


Syntax 


#include <ldap.h> 


int ldap_msgfree ( 
LDAPMessage *msg) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_msgfree() routine is used to free the memory allocated for an LDAP message by Idap_resultQ), 
Idap_search_sQ), ldap_search_ext_s(Q) or Idap_search_st(). It takes a pointer to the result to be freed and 


returns the type of the message it freed. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


msg 
(Input) Specifies pointer to the memory allocated for an LDAP message by Idap_resultQ, 
Idap_search_sQ), Idap_search_ext_sQ) or ldap_search_st(). 


Return Values 


Message Type 
the type of the message freed. 


ZERO 
if the input pointer to LDAPMessage structure is NULL. 


Error Conditions 


The Idap_msgfree() API returns ZERO if the input pointer to LDAPMessage structure is NULL. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_msgfree API. 


Related Information 


e |dap_ber_free( -- Free the BerElement structure. 


e idap_control_freeQ -- Free a single LDAPControl structure. 


e idap_controls_free() -- Free an array of LDAPControl structures. 


e idap_free_urldesc -- Free an LDAP URL Description 
e idap_memfree() -- Free storage allocated by the LDAP client library. 
e idap_mods_free( -- Free an array of pointers to mod structures. 


e Idap_result -- Retrieve result of an asynchronous LDAP operation. 


e Idap_search_ext_s -- Synchronously search the directory using controls. 


e Idap_search_s -- Perform an LDAP search operation (synchronous). 
e idap_search_st -- Perform an LDAP search operation (timed synchronous). 
e idap_server_free_list -- Free the List of LDAP Servers 


e idap_value_free -- Free memory allocated by Idap_get_values 
e Idap_value_free_len -- Free Memory Allocated by ldap_get_values_len 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_msgid()--Retrieve the Message ID 
Associated with an LDAP Message 


Syntax 


#include <ldap.h> 


int ldap_msgid ( 
LDAPMessage 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_msgid() routine returns the message ID associated with an LDAP message. Use Idap_msgid() to 
match the result(s) of an asynchronous operation with the original operation. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


msg 


(Input) Specifies a pointer to a result, as returned from Idap_first_message(), Idap_next_message, 


Idap_first_entryQ, ldap_next_entryQ), ldap _first_reference(), or ldap_next_reference(). 


Return Value 


Message ID 


if the call was successful. 


ZERO 
if the input pointer to LDAPMessage structure is NULL. 


Error Conditions 


Idap_msgid() returns ZERO if the input pointer to LDAPMessage structure is NULL. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_msgid API. 


Related Information 


Idap_addQ -- Perform an LDAP add operation. 

Idap_add_extQ) -- Perform an LDAP add operation with controls. 
Idap_bindQ -- Perform an LDAP bind request. 

Idap_compare() -- Perform an LDAP compare operation. 
Idap_compare_ext() -- Perform an LDAP compare operation with controls. 


Idap_deleteQ) -- Perform an LDAP delete operation. 


Idap_delete_extQ) -- Perform an LDAP delete operation with controls. 


ldap_extended_operation() -- Perform extended operations. 


Idap_first_entry( -- Retrieve first LDAP entry. 


ldap_first_message() -- Retrieve First LDAP message. 


Idap_first_reference( -- Return first continuation reference in a chain of search results. 


Idap_modifyQ -- Perform an LDAP modify entry request. 


Idap_modify_extQ -- Perform an LDAP modify entry request with controls. 
Idap_modrdnQ -- Perform an LDAP modify RDN request. 
ldap_msgtypeQ -- Returns the type of an LDAP message. 


Idap_next_entryQ -- Retrieve next LDAP entry. 


Idap_next_message() -- Retrieve Next LDAP message. 


Idap_next_reference() -- Retrieve next continuation reference in a chain of search results. 
ldap_rename() -- Asynchronously rename an entry. 

Idap_resultQ -- Wait for result from an asynchronous operation. 

Idap_sasl_bindQ -- Perform an LDAP SASL bind request. 

Idap_searchQ -- Perform an LDAP search operation. 


Idap_search_extQ) -- Asynchronously search the directory using controls. 


e |dap_simple_bindQ -- Perform a simple LDAP bind request. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_msgtype()--Retrieve the Type of an LDAP 
Message 


Syntax 


#include <ldap.h> 


int ldap_msgtype ( 
LDAPMessage 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_msgtype() API returns the type of an LDAP message. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


msg 


(Input) Specifies a pointer to a result, as returned from Idap_first_message(), Idap_next_message, 


Idap_first_entryQ, ldap_next_entryQ), ldap_first_reference(), or ldap_next_reference(). 


Return Value 


Message Type 


if the call was successful. Message types are as follows: 
LDAP_RES_BIND (0x61) Result of an LDAP bind operation. 


LDAP_RES_SEARCH_ENTRY 


(0x64) An entry. 


LDAP_RES_SEARCH_RESULT 


(0x65) Result of an LDAP search operation (LDAP v3). 


LDAP_RES_MODIFY (0x67) Result of an LDAP modify operation. 


LDAP_RES_ADD (0x69) Result of an LDAP add operation. 
LDAP_RES_DELETE (0x6b) Result of an LDAP delete operation. 
LDAP_RES_MODRDN (0x6d) Result of an LDAP modrdn operation. 
LDAP_RES_COMPARE (0x6f) Result of an LDAP compare operation. 


LDAP_RES SEARCH REFERENCE 
A search reference. 


(0x73) 
LDAP_RES_EXTENDED (0x78) Result of an LDAP extended operation (LDAP v3). 
LDAP_RES_REFERRAL (0xa3) A referral. 


ZERO 
if the input pointer to LDAPMessage structure is NULL. 


Error Conditions 


The Idap_msgtype() API returns ZERO if the input pointer to LDAPMessage structure is NULL. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_msgtype API. 


Related Information 


e idap_first_entry( -- Retrieve first LDAP entry. 
e idap_first_message() -- Retrieve first LDAP message. 


e lIdap_first_reference( -- Retrieve first continuation reference in a chain of search results. 
e idap_msgidQ -- Returns the ID of an LDAP message. 


e Idap_next_message() -- Retrieve next LDAP message. 


e Idap_resultQ -- Wait for result from an asynchronous operation. 


API introduced: V4R5 
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Idap_next_attribute()--Retrieve Next Attribute in 
an Entry 


Syntax 


#include <ldap.h> 


char *ldap_next_attribute ( 
LDAP *ld, 
LDAPMessage *entry, 
BerElement *berptr) 


Default Public Authority: *USE 
Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_next_attribute() function returns the next attribute in an entry. 


The Idap_next_attribute() function takes an entry returned by ldap_first_entryQ or ldap_next_entry() and 
returns a pointer to a buffer containing the next attribute type in the entry. This string must be freed when 


its use is completed using ldap_memfree(). 


The Idap_first_attributeQ) and Idap_next_attribute() functions are used to step through the attributes in an 
LDAP entry. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


entry 
(Input) The attribute information as returned by Idap_first_entryQ or ldap_next_entry(). 


berptr 


(Input/Output) This parameter specifies a pointer to a BerElement that was allocated by 
Idap_first_attributeQ to keep track of the current position. The BerElement structure is opaque to 


the application. The caller should free berptr using ldap_ber_freeQ) when finished. 


Return Value 


Pointer to a buffer containing the next attribute type in the entry 
if the request was successful. 
NULL 


When there are no attributes left to be retrieved. 


Error Conditions 


If ldap_next_attribute() is not successful, NULL is returned, and /d_errno will be set to indicate the error. 
See LDAP Client API Error Conditions for possible LDAP error code values. Use Idap_get_errnoQ 


function to retrieve the error information. It is left to the user to free outstanding BerElements using 


Idap_ber_free(). 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_next_attribute API. 


Related Information 


e idap_first_attributeQ -- Retrieve first attribute in an entry. 


e idap_first_entry( -- Retrieve first LDAP entry. 


e idap_next_entryQ -- Retrieve next LDAP entry. 
e idap_count_attributes() -- Retrieve count of attributes for an LDAP entry. 


e idap_get_values() -- Retrieve a set of attribute values from an entry. 


e Idap_get_values_lenQ -- Retrieve a set of binary attribute values. 


API introduced: V4R3 
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Idap_next_entry()--Retrieve Next LDAP Entry 


Syntax 


#include <ldap.h> 
LDAPMessage *ldap_next_entry ( 


LDAP *Id, 
LDAPMessage *entry) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_next_entry() function takes the result from a previous call to ldap_first_entryQ or 
Idap_next_entry() and returns a pointer to the next entry in a chain of results. 


The entry returned by Idap_next_entry() can be used by functions such as Idap_get_dnQ, 
Idap_first_attributeQ, and ldap_get_values(), as well as other functions to obtain additional information 
about the entry. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(),ldap_ssl_initQ, or 
Idap_open(Q). 


entry 
(Input) Specifies a pointer to an entry returned on a previous call to Idap_first_entryQ or 
Idap_next_entry(). 


Return Value 


Pointer to the next entry in the result 


if the request was successful. 


NULL 


When there are no attributes left to be retrieved. 


Error Conditions 


If Idap_next_entry() is not successful, NULL is returned, /d_errno will be set to indicate the error. See 
LDAP Client API Error Conditions for possible LDAP error code values. Use Idap_get_errno() function to 


retrieve the error information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_next_entry API. 


Related Information 


e lIdap_first_entryQ -- Return first entry in a chain of search results. 


e idap_count_entries(Q) -- Return number of entries in a chain of search results. 


e Idap_get_entry_controls_npQ -- Extract server controls from an entry. 


e Idap_first_reference() -- Return first continuation reference in a chain of search results. 


e |dap_next_reference() -- Return next continuation reference in a chain of search results. 


e |dap_count_references() -- Return number of continuation reference in a chain of search results. 


e idap_parse_reference_npQ) -- Extract information from a continuation reference. 
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Idap_next_message()--Retrieve Next LDAP 
Message 


Syntax 


#include <ldap.h> 
LDAPMessage *ldap_next_message ( 


LDAP *ld, 
LDAPMessage *msg) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_next_message() function is used to step through the list of messages in a result chain, as returned 
by Idap_resultQ and Idap_first_message(). It is used to return a pointer to the next message from the list. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or 
Idap_open(). 


msg 


(Input) Specifies the message returned by a previous call to Idap_first_messageQ or 
Idap_next_message(). 


Return Value 


LDAPMessage * 


pointer to the next message in list. 


NULL 


when no more messages exist in the result set to be returned or if an error occurs. 


Error Conditions 


If Idap_next_message() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use the ldap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_next_message API. 


Related Information 


e idap_count_messages() -- Return the number of messages in a result chain. 
e Idap_first_entry() -- Retrieve first LDAP entry. 


e idap_first_message( -- Retrieve first LDAP message. 


e idap_first_reference() -- Return first continuation reference in a chain of search results. 
e Idap_msgfreeQ -- Free LDAP Result Message. 

e idap_msgidQ -- Retrieve Message ID Associated with an LDAP Message. 

e idap_msgtypeQ -- Retrieve Type of an LDAP Message. 


e |dap_result2error() -- Retrieve LDAP Error Information. 
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Idap_next_reference()--Retrieve the next 
Continuation Reference in a Chain of Search 
Results 


Syntax 


#include <ldap.h> 
LDAPMessage *ldap_next_reference ( 


LDAP *Id, 
LDAPMessage *result) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_next_reference() function is used to return the next continuation reference from the search result 
chain. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

result 
(Input) Specifies the result returned by a call to Idap_result() or one of the synchronous search 
routines (Idap_search_sQ, ldap_search_stQ, or ldap_search_ext_sQ). 

ref 


(Input) Specifies a pointer to a search continuation reference returned on a previous call to 
Idap_first_reference() or Idap_next_reference(). 


Return Value 


LDAPMessage * 


pointer to the next continuation reference. 


NULL 


when no more continuation references exist in the result set to be returned. 


Error Conditions 


If ldap_next_reference() is not successful, /d_errno will be set to indicate the error. See LDAP Client API 
Error Conditions for possible LDAP error code values. Use the ldap_get_errno() function to retrieve the 
error information. 


Error Messages 


The following message may be sent from this function 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_next_reference API. 


Related Information 


e idap_first_entryQ -- Return first entry in a chain of search results. 


e idap_next_entryQ -- Return next entry in a chain of search results. 


e idap_count_entryQ -- Return number of entry in a chain of search results. 


e Idap_get_entry_controls_npQ -- Extract server controls from an entry. 


e idap_count_reference() -- Return the number of continuation reference in a chain of search results. 


e idap_first_reference() -- Return first continuation reference in a chain of search results. 


e Idap_parse_reference_npQ) -- Extract information from a continuation reference. 
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Idap_open()--Perform an LDAP Open Operation 


Syntax 


#include <ldap.h> 
LDAP *ldap_open ( 


char *host, 
int port) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_open() function opens a connection to an LDAP server and allocates an LDAP structure, which is used to identify 
the connection and to maintain per-connection information. 


The Idap_open() function returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP 
functions such as Idap_bind() and Idap_search(). 


Although still supported, the use of Idap_open() is deprecated. The Idap_open() API allocates an LDAP structure and opens 
a connection to the LDAP server. Use of Idap_init(Q instead of Idap_open() is recommended. 


As atule of thumb, the LDAP application is typically running as LDAP version 2 when it uses Idap_open() to create the 
LDAP connection. The LDAP application is typically running as LDAP version 3 when it uses Idap_init() to create the 


LDAP connection. However, it was possible with the LDAP V2 API to call Idap_init() so that there may be cases where this 
rule of thumb is not true. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


host 
(Input) Several methods are supported for specifying one or more target LDAP servers, including the following: 


Explicit Specifies the name of the host on which the LDAP server is running. The host parameter may contain a 
Host List blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If 
present, the -port overrides the port parameter. 


The following are typical examples: 


ld=ldap_open ("sServer1", ldap_port); 
ld=ldap_open ("sServer2:1200", ldap_port); 
ld=ldap_open ("Serverl:800 server2:2000 server3", ldap_port); 


Localhost Tf the host parameter is NULL, the LDAP server will be assumed to be running on the local host. 


Default If the host parameter is set to LDAP_URL_PREFIX ("Idap://") the LDAP library will attempt to locate 
Hosts one or more default LDAP servers, with non-SSL ports, using the SecureWay Idap_server_locate() 


function. The port specified on the call is ignored, since Idap_server_locate() returns the port. 


For example, the following two are equivalent: 


ld=ldap_open ("l1dap://", ldap_port); 
ld=ldap_open (LDAP_URL_PREFIX, LDAP_PORT); 


If more than one default server is located, the list is processed in sequence, until an active server is found. 


The LDAP URL can include a Distinguished Name (DN), used as a filter for selecting candidate LDAP 
servers based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact 
match with a server's suffix (after normalizing for case), the server is added to the list of candidate 
servers. For example, the following will only return default LDAP servers that have a suffix that supports 
the specified DN: 


ld=ldap_open ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT); 


In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one 
default server is located, the list is processed in sequence, until an active server is found. 


If the LDAP URL contains a host name and optional port, the host is used to create the connection. No 
attempt is made to locate the default server(s), and the DN, if present, is ignored. 


For example, the following two are equivalent: 


ld=ldap_open ("ldap://myserver", LDAP_PORT) ; 
ld=ldap_open ("myserver", LDAP_PORT) ; 


Local If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX socket 

Socket (that is, socket family is AF_UNIX) and port is ignored. Use of a UNIX socket requires the LDAP server 
to be running on the local host. In addition, the LDAP server must be listening on the specified UNIX 
socket. The OS/400 Secureway Directory Services server listens on the /tmp/s.slapd local socket, in 
addition to any configured TCP/IP ports. 


For example: 
ld=ldap_open ("/tmp/s.slapd", ldap_port); 


Host with Tf a specified host is prefixed with "privport://", then the LDAP library will use the rresvport() function to 

Privileged attempt to obtain one of the reserved ports (512 through 1023), instead of an "ephemeral" port. The search 

Port for a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call 
will fail. 


For example: 


ld=ldap_open ("privport://serverl,1ldap_port"); 

ld=ldap_open ("privport://server2:1200", ldap_port) ; 

ld=ldap_open ("privport://server1:800 server2:2000 privport://server3", 
ldap_port); 


port 


(Input) Specifies the TCP port number the server is listening on. If the default IANA-assigned port of 389 is desired, 
LDAP_PORT should be specified. To use the default SSL port 636 for SSL connections, use LDAPS_PORT. 


Return Value 


Pointer to an LDAP structure 


if the request was successful. 


NULL 


if the request was not successful. 


Error Conditions 


The Idap_open() API will return NULL and set the /d_errno error code, if not successful. See LDAP Client API Error 
Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_open API. 


Related Information 


e ldap _init() -- Initializes a session with an LDAP server. 

e ldap_set_option() -- Set an option associated with an LDAP descriptor. 
e lIdap_get_option() -- Get an option associated with an LDAP descriptor. 
e ldap_version() -- Obtain LDAP version and SSL cipher information. 


API introduced: V4R3 
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Idap_parse_extended_result()--Parse extended 
result 


Syntax 


#include <ldap.h> 


int ldap_parse_extended_result ( 
LDAP Lie 
LDAPMessage *res, 
char *xresultoidp, 
struct berval **resultdatap, 
int freeit) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_parse_extended_result() function is used to parse the result of an extended operation intiated by 
Idap_extended_operation(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

res 
(Input) Specifies the result of an LDAP operation as returned by Idap_first_messageQ or 
ldap_next_message() where the message type is LDAP_RES_EXTENDED. 

resultoidp 
(Input) This result parameter specifies a pointer which is set to point to an allocated, dotted-OID 
text string returned from the server. This string should be disposed of using the ldap_memfree() 
API. If no OID is returned, *resultoidp is set to NULL. 

resultdatap 


(Input) This result parameter specifies a pointer to a berval structure pointer that is set to an 
allocated copy of the data returned by the server. This struct berval should be disposed of using 
ber_bvfree(). If no data is returned, *resultdatap is set to NULL. 


freeit 


(Input) Specifies a boolean value that determines if the LDAP result (as specified by res) is to be 
freed. Any non-zero value will result in res being freed after the requested information is extracted. 
Alternatively, the ldap_msgfree() API can be used to free the result at a later time. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_extended_result() is not successful, /d_errno will be set to indicate the error. See LDAP Client 
API Error Conditions for possible LDAP error code values. ldap_get_errno() function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_parse_extended_result API. 


Related Information 


e Idap_extended_operation -- Perform extended operation 


e Idap_extended_operation_s -- Perform extended operations synchronously. 


e idap_first_message() -- Retrieve first LDAP message. 

e idap_msgtypeQ -- Retrieve the type of an LDAP message. 

e |dap_next_message() -- Retrieve next LDAP message. 

e idap_result -- Retrieve Result of an Asynchronous LDAP Operation 


The Idap_parse_extended_result() API supports LDAP V3 server controls and client controls. 
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Idap_parse_reference_np()--Extract Information 
from a Continuation Reference 


Syntax 


#include <ldap.h> 


int ldap_parse_reference_np (LDAP *ld, 
LDAPMessage *ref, 
char xxx referralsp, 
LDAPControl *** serverctrilsp, 
int freeit) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_parse_reference_np() function is used to retrieve the list of alternate servers returned in an 
individual continuation reference in a chain of search results. This routine is also used to obtain an array of 
server controls returned in the continuation reference. 


Note the suffix "_np" which shows the API is in a preliminary implementation, and is not documented in 
the Internet Draft. The internet community may standardize this API in the future. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

ld 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

ref 
(Input) Specifies a pointer to a search continuation reference returned on a previous call to 
Idap_first_referenceQ) or ldap_next_reference(). 

referralsp 


(Output) Specifies a pointer to a result parameter that is filled in with the contents of the referrals 
field from the LDAPMessage ref, indicating zero or more alternate LDAP servers where the 
request should be retried. The referrals array should be freed by calling Idap_value_freeQ. NULL 


may be supplied for this parameter to ignore the referrals field. 
serverctrisp 


(Input) Specifies a pointer to a result parameter that is filled in with an allocated array of controls 
copied out of the LDAPMessage ref. The control array should be freed by calling 
Idap_controls_free(). 


freeit 


(Input) Specifies a boolean value that determines if the LDAP result chain (as specified by ref) is to 
be freed. Any non-zero value will result in the LDAP result chain being freed after the requested 
information is extracted. Alternatively, the ldap_msgfree() API can be used to free the LDAP result 


chain at a later time. 


Return Value 


LDAP_SUCCESS 


if the call was successful. 


another LDAP error code 


if the call was not successful. 


Error Conditions 


The Idap_parse_reference_np() function will return an LDAP error code if not successful. See LDAP 
Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_parse_reference_np API. 


Related Information 


e idap_first_entry( -- Return first entry in a chain of search results. 


e idap_next_entry( -- Return next entry in a chain of search results. 


e idap_count_entry( -- Return number of entry in a chain of search results. 


e ldap_get_entry_ controls npQ -- Extract server controls from an entry. 


e idap_count_reference() -- Return the number of continuation reference in a chain of search results. 


e lIdap_first_reference( -- Return first continuation reference in a chain of search results. 


e@ Idap_next_reference() -- Return next continuation reference in a chain of search results. 
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Idap_parse_result()--Extract Information from 
Results 


Syntax 


#include <ldap.h> 


int ldap_parse_result ( 
LDAP *ld, 
LDAPMessage *res, 
int *errcodep, 
char **matcheddnp, 
char **xerrmsgp, 
char *x* referralsp, 
LDAPControl **x**servctrilsp, 
int freeit) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_parse_result() routine is used to: 
e Obtain the LDAP error code field associated with an LDAPMessage res. 


Obtain the portion of the DN that the server recognizes for a failed operation. 


® 
e Obtain the text error message associated with the error code returned in an LDAPMessage res. 
e Obtain the list of alternate servers from the referrals field. 

® 


Obtain the array of controls that may be returned by the server. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

res 
(Input) Specifies the result of an LDAP operation as returned by Idap_resultQ or one of the 


synchronous LDAP API operation calls. 
errcodep 


(Output) Specifies a pointer to the result parameter that will be filled in with the LDAP error code 
field from the LDAPMessage res. The LDAPResult message is produced by the LDAP server, and 
indicates the outcome of the operation. NULL can be specified for errcodep if the error code is to 
be ignored. 


matcheddnp 


(Output) Specifies a pointer to a result parameter. When LDAP_NO_SUCH_OBJECT is returned 
as the LDAP error code, this result parameter will be filled in with a Distinguished Name indicating 
how much of the name in the request was recognized by the server. NULL can be specified for 
matcheddnp if the matched DN is to be ignored. The matched DN string should be freed by calling 


Idap_memfree(). 


errmsgp 


(Output) Specifies a pointer to a result parameter that is filled in with the contents of the error 
message from the LDAPMessage res. The error message string should be freed by calling 


Idap_memfree(). 


referralsp 


(Output) Specifies a pointer to a result parameter that is filled in with the contents of the referrals 
field from the LDAPMessage res, indicating zero or more alternate LDAP servers where the 
request should be retried. The referrals array should be freed by calling Idap_value_freeQ. NULL 


may be supplied for this parameter to ignore the referrals field. 


serverctrisp 


(Ourput) Specifies a pointer to a result parameter that is filled in with an allocated array of controls 
copied out of the LDAPMessage res. The control array should be freed by calling 
Idap_controls_free(Q. 


freeit 


(Input) Specifies a boolean value that determines if the LDAP result chain (as specified by res) is to 
be freed. Any non-zero value will result in the LDAP result chain being freed after the requested 
information is extracted. Alternatively, the ldap_msgfree() API can be used to free the LDAP result 


chain at a later time. 


Return Value 


LDAP_SUCCESS 


if the result was successfully located and parsed. 


another LDAP error code 


if not successfully parsed. 


Error Conditions 


The Idap_parse_result() function will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_parse_result API. 


Related Information 


e idap_first_message() -- Retrieve first LDAP message. 
e |dap_next_message() -- Retrieve next LDAP message. 


e Idap_parse_extended_resultQ -- Parse extended result. 


e |idap_parse_sasl_bind_result() -- Extract server credentials from SASL bind results. 


e idap_resultQ -- Retrieve result of an asynchronous LDAP operation. 
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Idap_parse_sasl_bind_result()--Extract Server 
Credentials from SASL Bind Results 


Syntax 


#include <ldap.h> 


int ldap_parse_sasl_bind_result ( 
LDAP *ld, 
LDAPMessage *res, 
struct berval ** servercredp, 
int freeit) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_parse_sasl_bind_result() function is used to obtain server credentials, as a result of an attempt 
to perform mutual authentication. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

res 
(Input) Specifies the result of an LDAP operation as returned by Idap_resultQ or one of the 
synchronous LDAP API operation calls. 

servercredp 
(Output) Specifies a pointer to a result parameter. For SASL bind results, this result parameter will 
be filled in with the credentials returned by the server for mutual authentication (if returned). The 
credentials, if returned, are returned in a struct berval. NULL may be supplied to ignore this field. 

freeit 


(Input) Specifies a boolean value that determines if the LDAP result chain (as specified by ref) is to 
be freed. Any non-zero value will result in the LDAP result chain being freed after the requested 
information is extracted. Alternatively, the ldap_msgfree() API can be used to free the LDAP result 


chain at a later time. 


Return Value 


LDAP_SUCCESS 


if the result was successfully located and parsed. 


another LDAP error code 


if not successfully parsed. 


Error Conditions 


The Idap_parse_sasl_bind_result() function will return an LDAP error code if not successful. See LDAP 
Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_parse_sasl_bind_result API. 


Related Information 


e l|dap_first_message() -- Retrieve first LDAP message. 


Idap_next_message() -- Retrieve next LDAP message. 


e idap_parse_result() -- Extract information from results. 
e idap_sasl_bindQ -- Perform an LDAP SASL bind request. 
Idap_sasl_bind_sQ) -- Perform an LDAP SASL bind request (synchronous). 
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Idap_perror()--Print LDAP Error Information 


Syntax 


#include <ldap.h> 
void ldap_perror ( 


LDAP kid, 
const char *s) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_perror() function prints an indication of the error on standard error. The error string printed out 
will be in English only. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


ld 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


(Input) Specifies the message prefix, which is prepended to the string form of the error code stored 
in the LDAP structure. The string form of the error is the same string that would be returned by a 
call to Idap_err2string(Q. 


Return Value 


None 


Error Conditions 


The Idap_perror() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_perror API. 


Related Information 


e Idap_get_errnoQ -- Retrieve error code set. 


e Idap_get_Iderrno(Q -- Retrieve error information. 
e idap_err2string( -- Convert LDAP error indication to a string. 
e Idap_result2errorQ -- Extract LDAP error indication from LDAP result. 
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Idap_rename()--Asynchronously Rename an 
Entry 


Syntax 


#include <ldap.h> 


int ldap_rename ( 
LDAP * 1d, 
const char *dn, 
const char *newrdn, 
const char *newparent, 
int deleteoldrdn, 
LDAPControl **k serverctrls, 
LDAPControl k*xkclientctrls, 
int *xmsgidp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_rename() routine initiates an asynchronous modify DN operation 


In LDAP version 2, the ldap_modrdn() API was used to change the name of an LDAP entry. It could only 


be used to change the least significant component of a name (the RDN or relative distinguished name). The 
LDAP version 3 protocol provides the Modify DN protocol operation that allows more general name 
change access. The Idap_rename() routine is used to change the name of an entry. The Idap_modrdn() 
routine is deprecated. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 
(Input) Specifies the DN of the entry whose DN is to be changed. 


newrdn 


(Input) Specifies the new RDN to be given to the entry. 
newparent 


(Input) Specifies the new parent, or superior entry. If this parameter is NULL, only the RDN of the 
entry is changed. The root DN may be specified by passing a zero length string, "". The newparent 
parameter should always be NULL when using version 2 of the LDAP protocol; otherwise the 
server's behavior is undefined. 


deleteoldrdn 


(Input) Specifies a boolean value. When set to 1, the old RDN value is to be deleted from the entry. 
When set to 0, the old RDN value should be retained as a non-distinguished value. This parameter 
only has meaning if newrdn is different from the old RDN. 


serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 

msgidp 


(Output) This result parameter is set to the message id of the request if the Idap_rename() call 
succeeds. 


Return Value 


LDAP_SUCCESS 


if the request was successfully sent. Idap_rename() places the message id of the request in 
*msgidp. A subsequent call to ldap_resultQ can be used to obtain the result of the operation. Once 
the operation has completed, Idap_result() returns a result that contains the status of the operation 
(in the form of an error code). The error code indicates if the operation completed successfully. The 
Idap_parse_resultQ) API is used to check the error code in the result. 


another LDAP error code 


in case of an error. 


Error Conditions 


If l\dap_rename() is not successful, an error code will be returned. See LDAP Client API Error Conditions 
for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_rename API. 


Related Information 


e idap_rename_sQ) -- Synchronously rename an entry. 

e Idap_resultQ -- Retrieve result of an asynchronous LDAP operation. 

e Idap_modrdnQ -- Asynchronously modify the RDN of an entry (deprecated). 
e Idap_modrdn_sQ) -- Synchronously modify the RDN of an entry (deprecated). 


The Idap_rename() API supports LDAP V3 server controls and client controls. 
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Idap_rename_s()--Synchronously Rename an 
Entry 


Syntax 


#include <ldap.h> 


int ldap_rename_s ( 
LDAP * 1d, 
const char *dn, 
const char *newrdn, 
const char *newparent, 
int deleteoldrdn, 
LDAPControl **k serverctrls, 
LDAPControl *xkclientctrls) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_rename_s() routine performs a synchronous modify DN operation. 


In LDAP version 2, the ldap_modrdn_s() API was used to change the name of an LDAP entry 


synchronously. It could only be used to change the least significant component of a name (the RDN or 
relative distinguished name). The LDAP V3 protocol provides the Modify DN protocol operation that 
allows more general name change access. The Idap_rename_s() routine is used to change the name of an 
entry, and the use of the Idap_modrdn_s() routine is deprecated. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ), or 
Idap_open(). 


dn 
(Input) Specifies the DN of the entry whose DN is to be changed. 
newrdn 


(Input) Specifies the new RDN to be given to the entry. 


newparent 


(Input) Specifies the new parent, or superior entry. If this parameter is NULL, only the RDN of the 
entry is changed. The root DN may be specified by passing a zero length string, "". The newparent 
parameter should always be NULL when using version 2 of the LDAP protocol; otherwise the 
server's behavior is undefined. 


deleteoldrdn 


(Input) Specifies a boolean value. When set to non-zero, the old RDN value is removed from the 
entry. When set to 0, the old RDN value will be retained as a non-distinguished value. This 
parameter only has meaning if newrdn is different from the old RDN. 


serverctrls 


(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 


clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


Return Value 


LDAP_SUCCESS 


if the request was successfully. 


another LDAP error code 


in case of an error. 


Error Conditions 


If ldap_rename_s() is not successful, an error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_rename_s API. 


Related Information 


e Idap_renameQ -- Asynchronously rename an entry. 
e Idap_modrdnQ -- Asynchronously modify the RDN of an entry (deprecated). 


e |dap_modrdn_sQ -- Synchronously modify the RDN of an entry (deprecated). 


The Idap_rename_s() API supports LDAP V3 server controls and client controls. 
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Idap_result()--Retrieve Result of an 
Asynchronous LDAP Operation 


Syntax 


#include <sys/time.h> 
#include <ldap.h> 


int ldap_result ( 
LDAP KL, 
int msgid, 
int all, 
struct timeval *timeout, 
LDAPMessage ** result) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_result() function is used to wait for and return the result of an operation previously initiated by 
one of the LDAP asynchronous operation functions (such as Idap_search() and Idap_modifyQ). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

msgid 
(Input) Specifies the message ID of the operation whose results are to be returned. The parameter 
can be set to LDAP_RES_ANY if any result is desired. 

all 


(Input) This parameter only has meaning for search results. For search results, all is used to specify 
how many search result messages will be returned on this call to Idap_result(). Specify 
LDAP_MSG_ONE to retrieve one search result message (for example, a single entry). Specify 
LDAP_MSG_ALL to request that all results of a search be received. Idap_result() will wait until 
all results are received before returning the results in a single chain. Specify 
LDAP_MSG_RECEIVED to indicate that all results retrieved so far should be returned in the result 
chain. 


timeout 


(Input) Specifies how long in seconds to wait for results (as identified by the supplied msgid) to be 
returned from Idap_result. A NULL value causes Idap_result() to wait until results for the 
operation identified by msgid are available. To poll, the timeout parameter should be non-NULL, 
pointing to a zero-valued timeval structure. 


result 


(Output) Contains the result of the asynchronous operation identified by msgid. This value should 
be freed by ldap_msgfreeQ when the result is no longer needed. 


Return Value 


-1 
If Idap_result() was unsuccessful, sets the appropriate LDAP error, and Idap_get_errno() API can 
be used to obtain the error code. 

0 
If ldap_result() times out or there is no message available. 

If successful, 


it returns one of the following result types: 


LDAP_RES_BIND Ox61L 
LDAP_RES_SEARCH_ENTRY Ox64L 
LDAP_RES_SEARCH_RESULT Ox65L 
LDAP_RES_MODIFY 0x67L 
LDAP_RES_ADD Ox69L 
LDAP_RES_DELETE Ox6bL 
LDAP_RES_MODRDN Ox6dL 
LDAP_RES_COMPARE Ox6fL 
LDAP_RES_SEARCH_REFERENCE OX73L 
LDAP_RES_EXTENDED OX78L 
LDAP_EXTENDED_RES_NAME OX8aL 
LDAP_EXTENDED_RES_VALUE OX8bL 
LDAP_RES_REFERRAL OXa3L 


LDAP_RES_ANY (-1L) 


Error Conditions 


If Idap_result() is not successful, /d_errno will be set to indicate the error. See LDAP Client API Error 
Conditions for possible values of /d_errno field. Use ldap_get_errnoQ function to retrieve the error 
information. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_result API. 


Related Information 


e idap_count_messages() -- Count messages in a result chain. 


e idap_first_entry(Q -- Retrieve first LDAP entry. 


e idap_first_message() -- Retrieve first LDAP message. 

e idap_first_referenceQ( -- Retrieve first continuation reference in a chain of search results. 
e idap_msgfreeQ -- Free LDAP result message. 

e idap_msgidQ -- Retrieve the message ID associated with an LDAP message. 

e idap_msgtypeQ -- Returns the type of an LDAP message. 

e idap_msgidQ) -- Returns the ID of an LDAP message. 


e idap_parse_resultQ -- Extract information from results. 
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Idap_result2error()--Retrieve LDAP Error 
Information 


Syntax 


#include <ldap.h> 


int ldap_result2error ( 
LDAP *1id, 
LDAPMessage *res, 
int freeit) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_result2error() API takes a result as produced by Idap_result(Q or Idap_search_s(), and returns the 
corresponding error code. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or 
Idap_open(). 

res 
(Input/Output) Specifies the result, as produced by Idap_result(), to be converted to the error code 
with which it is associated. 

freeit 


(Input) Specifies whether or not the result, res, should be freed as a result of calling 
Idap_result2error(). If non-zero, the result, res, will be freed by the call. If zero, res will not be 
freed by the call. 


Return Value 


LDAP error code 


The result of the ldap request in res. 


Error Conditions 


The Idap_result2error() function will return an LDAP error code. See LDAP Client API Error Conditions 
for possible LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_result2error API. 


Related Information 


e idap_err2string( -- Convert LDAP error indication to a string. 

e |dap_get_errno( -- Retrieve error information. 

e l|dap_perror() -- Print an LDAP error indication to standard error. 

e Idap_resultQ -- Retrieve result of an asynchronous LDAP operation. 


e Idap_search_s() -- Perform an LDAP search operation (synchronous). 
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Idap_sasl_bind()--Perform an LDAP SASL Bind 
Request 


Syntax 


#include <ldap.h> 


int ldap_sasl_bind ( 
LDAP *k1d,; 
const char *dn, 
const char *mechanism, 
const struct berval *cred, 
LDAPControl **serverctrls, 
LDAPControl *xkclientctrls, 
int *xmsgidp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_sasl_bind() function is used to authenticate a distinguished name (DN) to a directory server 
using Simple Authentication Security Layer (SASL). 


After a connection is made to an LDAP V2 server an LDAP bind API must be called before any other 
LDAP APIs can be called for that connection. For LDAP V3 servers, binding is optional. 


Idap_sasl_bind() is an asynchronous request. The result of the operation can be obtained by a subsequent 


call to ldap_resultQ. 


None of the mechanisms provided with OS/400 support the use of asynchronous SASL bind. You must use 
Idap_sasl_bind_sQ. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 


(Input) Specifies the Distinguished Name of the entry to bind as. 
mechanism 


(Input) This value can be set to NULL to perform a simple bind. Other mechanisms (EXTERNAL, 
CRAM-MDS, and GSSAPD are implemented, but do not support the asynchronous SASL bind. 
You must use Idap_sasl_bind_s() for other mechanisms. 


cred 
(Input) Specifies the credentials with which to authenticate. Arbitrary credentials can be passed 
using this parameter. In most cases, this is the user's password. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 

msgidp 


(Output) This result parameter is set to the message id of the request if the Idap_sasl_bind() call 
succeeds. 


Return Value 


Message ID of the Operation Initiated 
if the request was successful. A subsequent call to Idap_result(), can be used to obtain the result. 


Another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_sasl_bind() is not successful, an error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_sasl_bind API. 


Related Information 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 


e idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 


e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_sasl_bind_s()--Perform an LDAP SASL 
Bind Request (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_sasl_bind_s ( 
LDAP *k1d,; 
const char *dn, 
const char *mechanism, 
const struct berval *cred, 
LDAPControl **serverctrls, 
LDAPControl *xclientctrls, 
struct berval ** servercredp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_sasl_bind_s() function can be used to do general authentication over LDAP through the use of 
the Simple Authentication Security Layer (SASL). 


After a connection is made to an LDAP V2 server an LDAP bind API must be called before any other 
LDAP APIs can be called for that connection. For LDAP V3 servers, binding is optional. 


Idap_sasl_bind_s() performs a synchronous request. 


Authorities and Locks 


For the EXTERNAL mechanism, *R authority is needed to the selected Certificate Store and *X authority 
is needed to each directory of its path. 


Parameters 


Id 
(Input) The LDAP pointer returned by a previous call to Idap_initQ, ldap_ssl_initQ, or ldap_openQ. 


dn 
(Input) The Distinguished Name of the entry to bind as, may be NULL. 


mechanism 


cred 


(Input) Although a variety of mechanisms have been IANA registered, the mechanisms supported 
by the library at this time are: 


o LDAP_MECHANISM_EXTERNAL mechanism, represented by the string 
"EXTERNAL". 


o LDAP_MECHANISM_CRAMMDS5 mechanism, represented by the string 
"CRAM-MDS". 


o LDAP_MECHANISM_GSSAPI mechanism, represented by the string "GSSAPI". 


By setting mechanism to a NULL pointer, the SASL bind request will be interpreted as a request 
for simple authentication (equivalent to using Idap_simple_bind_sQ). 


The LDAP_MECHANISM_EXTERNAL mechanism indicates to the server that information 
external to SASL should be used to determine whether the client is authorized to authenticate. For 
this implementation, the system providing the external information must be SSL. The server will 
use the identity from the client's X.509 certificate that was chosen using the ldap_ssl_client_initO 
and Idap_ssl_initQ or ldap_app_ssl_client_init_npQ API. The dn and cred parameters must be 
NULL. 


The LDAP_MECHANISM_CRAMMDS5 mechanism is used to authenticate with the server using 
a challenge/response protocol that protects the "clear-text" password over the wire. This 
mechanism is useful only when the LDAP server can retrieve the user's password. The contents of 
the cred berval must be a UTF8 representation of the password. See Idap_xlate_local_to_utf8Q for 


converting local data to UTF8. 


The LDAP_MECHANISM_GSSAPI mechanism is used to enable Kerberos authentication. The 
dn parameter must be NULL. If the cred parameter is NULL, then it is assumed that the user has 
already authenticated to a Kerberos security server and has obtained a Ticket Granting Ticket 
(TGT) using a program such as kinit. The GSSAPI credential handle used to initiate a security 
context on the LDAP client side is obtained from the current login context. The cred parameter can 
also point to a berval containing a GSSAPI credential handle that will be used to initiate a security 
context with the LDAP server. For example, a server application can call Idap_sasl_bind_s with a 
credential handle that the server received from a client as a delegated credential handle. 


(Input) Specifies the credentials with which to authenticate. Arbitrary credentials can be passed 
using this parameter. In most cases, this is the user's password. 


serverctrls 


(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 


clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


servercredp 


(Output) This result parameter will be set to the credentials returned by the server. If no credentials 
are returned, it will be set to NULL. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If Idap_sasl_bind_s() is not successful, an error code is returned. See LDAP Client API Error Conditions 
for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_sasl_bind_s API. 


Related Information 


e Idap_init -- Perform an LDAP initialization operation, 
e idap_ssl_client_init -- Initializes the SSL library. 


e idap_ssl_init -- Initializes an SSL connection. 
e idap_app_ssl_client_init_np -- Initialize the LDAP client for a secure connection using DCM. 


e idap_app_ssl_init_np -- Initializes an SSL connection. 


e |idap_sasl_bindQ -- Asynchronously bind to the directory using the Simple Authentication Security 
Layer (SASL). 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 
e idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 
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Idap_search()--Perform an LDAP Search 
Operation 


Syntax 


#include <ldap.h> 


int ldap_search ( 
LDAP RL, 
const char *base, 
ine Scope, 
const char *filter, 
char *xattrs, 
int attrsonly) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_search() function is used to perform an LDAP search operation. 


Idap_search() is an asynchronous request. A subsequent call to Idap_resultQ can be used to obtain the results 
from the search. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or 
Idap_open(). 


(Input) Specifies the DN of the entry at which to start the search. 
scope 


(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the base object 
itself), or LDAP_SCOPE_ONELEVEL (to search the base object's immediate children), or 
LDAP_SCOPE_SUBTREE (to search the base object and all its descendents). 


filter 


(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be 
specified as attributetype=attributevalue. More complex filters are specified using a prefix notation 
according to the following BNF: 


<filter> ::= '(' <filtercomp> ')' 
<filtercomp> ::= <and> | <or> | <not> | <simple> 
<and> ::= '&' <filterlist> 
<or> sae (|) 2fiiterliet> 
<not> :3:= '!' <filter> 
<filterlist> <!= <filter> | <filter> <filterlist> 
<simple> ::= <attributetype> <filtertype> <attributevalue> 
<filtertype> ::= '=' | ‘w=! | "<=! | '>=! 
The '~=' construct is used to specify approximate matching. The representation for <attributetype> 


and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): 
Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute 
existence test, or can contain text and *'s interspersed to achieve substring matching. 


For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter 
"(mail=* @student.of.life.edu)" will find any entries that have a mail attribute ending in the specified 
string. 


More complex filters are created using the & and | operators. For example, the filter 
"(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail 
attribute. To put parentheses or asterisks in a filter, escape them with a backslash ‘\' character. See 
RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of 
allowable filters. 


attrs 
(Input) Specifies a null-terminated array of character string attribute types to return from entries that 
match filter. If NULL is specified, all attributes will be returned. 

attrsonly 


(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set 
to 0 to request both attributes types and attribute values. 


Return Value 


Message ID of the Operation Initiated 
if the request was successful. A subsequent call to Idap_result(), can be used to obtain the result. 


if the request was not successful. 


Error Conditions 


If Idap_search() is not successful, -1 will be returned setting the session error(/d_errno) parameters in the 
LDAP structure appropriately. See LDAP Client API Error Conditions for possible values for the error codes. 


Use Idap_get_errno() to obtain the error code /d_errno. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_search API. 


Related Information 


e Idap_resultQ -- Retrieve result of an asynchronous LDAP operation. 

e Idap_search_sQ -- Synchronously search the directory. 

e Idap_search_ext() -- Asynchronously search the directory with controls. 
e Idap_search_ext_sQ) -- Synchronously search the directory with controls. 


e |dap_search_st() -- Synchronously search the directory with timeout. 
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Idap_search_ext --Asynchronously Search the 
Directory Using Controls 


Syntax 


#include <ldap.h> 


int ldap_search_ext ( 
LDAP *ild, 
const char *base, 
int Scope, 
const char *filter, 
char eS abo LS 
int attrsonly, 
LDAPControl xk serverctrls, 
LDAPControl **olientctris, 
struct timeval *timeout, 
int sizelimit, 
int *msgidp) 


Default Public Authority: *USE 
Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_search_ext() routine initiates an asynchronous search operation. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


ld 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or 
Idap_open(). 


(Input) Specifies the DN of the entry at which to start the search. 
scope 


(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the base object 
itself), or LDAP_SCOPE_ONELEVEL (to search the base object's immediate children), or 
LDAP_SCOPE_SUBTREE (to search the base object and all its descendents). 


filter 


(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be 
specified as attributetype=attributevalue. More complex filters are specified using a prefix notation 
according to the following BNF: 


<filter> ::= '(' <filtercomp> ')' 

<filtercomp> ::= <and> | <or> | <not> | <simple> 

<and> ::= '&' <filterlist> 

Sox> sca 1% erilterlist> 

<not> ::= '!' <filter> 

<filterlist> ::= <filter> | <filter> <filterlist> 

<simple> ::= <attributetype> <filtertype> <attributevalue> 
<filtertype> ::= "=" | t's" | "<=! | Tos! 


The '~=' construct is used to specify approximate matching. The representation for <attributetype> 
and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): 
Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute 
existence test, or can contain text and *'s interspersed to achieve substring matching. 


For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter 
"(mail=* @ student.of.life.edu)" will find any entries that have a mail attribute ending in the specified 
string. 


More complex filters are created using the & and | operators. For example, the filter 
"(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail 
attribute. To put parentheses or asterisks in a filter, escape them with a backslash ‘\' character. See 
RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of 
allowable filters. 


attrs 
(Input) Specifies a null-terminated array of character string attribute types to return from entries that 
match filter. If NULL is specified, all attributes will be returned. 

attrsonly 
(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set 
to 0 to request both attributes types and attribute values. 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 

sizelimit 
(Input) Specifies the maximum number of entries to return. Note that the server may set a lower limit 
which is enforced at the server. 

timeout 
(Input) The local search timeout value and the operation time limit that is sent to the server within the 
search request. 

msgidp 


(Output) This result parameter is set to the message id of the request if the Idap_search_ext() call 
succeeds. 


Return Value 


Message ID of the Operation Initiated 
if the request was successful. A subsequent call to Idap_result(Q) can be used to obtain the result. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_search_ext() is not successful, an error code will be returned. See LDAP Client API Error Conditions 
for possible LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_search_ext API. 


Related Information 


e Idap_resultQ -- Retrieve result of an asynchronous LDAP operation. 
e Idap_search_sQ -- Synchronously search the directory. 
e |Idap_searchQ -- Asynchronously search the directory. 


e Idap_search_ext_sQ) -- Synchronously search the directory with controls. 


e Idap_search_st() -- Synchronously search the directory with timeout. 


The Idap_search_ext() API supports LDAP V3 server controls, client controls, and allow varying size and 
time limits to be easily specified for each search operation. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_search_ext_s -- Synchronously Search the 
Directory Using Controls 


Syntax 


#include <ldap.h> 


int ldap_search_ext_s ( 
LDAP *ld, 
const char *base, 
int SCOpe, 
const char ef leer, 
char ** ACCES, 
int attrsonly, 
LDAPControl xk serverctrls, 
LDAPControl k*xclientctrls, 
struct timeval *timeout, 
int sizelimit, 
LDAPMessage ** res) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_search_ext_s() routine initiates a synchronous search operation, allowing LDAP controls to be sent 
to the server and client. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


ld 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or 
Idap_open(). 


(Input) Specifies the DN of the entry at which to start the search. 
scope 


(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the object 
itself), or LDAP_SCOPE_ONELEVEL (to search the object's immediate children), or 
LDAP_SCOPE_SUBTREE (to search the object and all its descendents). 


filter 


(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be 
specified as attributetype=attributevalue. More complex filters are specified using a prefix notation 
according to the following BNF: 


<filter> ::= '(' <filtercomp> ')' 

<filtercomp> ::= <and> | <or> | <not> | <simple> 

<and> ::= '&' <filterlist> 

Sox> sca 1% erilterlist> 

<not> ::= '!' <filter> 

<filterlist> ::= <filter> | <filter> <filterlist> 

<simple> ::= <attributetype> <filtertype> <attributevalue> 
<filtertype> ::= "=" | t's" | "<=! | Tos! 


The '~=' construct is used to specify approximate matching. The representation for <attributetype> 
and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): 
Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute 
existence test, or can contain text and *'s interspersed to achieve substring matching. 


For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter 
"(mail=* @ student.of.life.edu)" will find any entries that have a mail attribute ending in the specified 
string. 


More complex filters are created using the & and | operators. For example, the filter 
"(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail 
attribute. To put parentheses or asterisks in a filter, escape them with a backslash ‘\' character. See 
RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of 
allowable filters. 


attrs 


(Input) Specifies a null-terminated array of character string attribute types to return from entries that 
match filter. If NULL is specified, all attributes will be returned. 


attrsonly 


(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set 
to 0 to request both attributes types and attribute values. 


serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 
(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 

sizelimit 
(Input) Specifies the maximum number of entries to return. Note that the server may set a lower limit 
which is enforced at the server. 

timeout 


(Input) The local search timeout value and the operation time limit that is sent to the server within the 
search request. 


res 


(Output) Contains the result of the synchronous search operation. This result should be passed to the 


LDAP parsing routines (see ldap_first_entryQ, ldap_next_entry(), and so on). The caller is 
responsible for freeing res with ldap_msgfree(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. The code can be interpreted by Idap_perror() or ldap_err2string(). 


Error Conditions 


If ldap_search_ext_s() is not successful, an error code will be returned. See LDAP Client API Error 
Conditions for possible values for the error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_search_ext_s API. 


Related Information 


e Idap_first_entryQ -- Retrieve first LDAP entry. 


e ldap _first_reference() -- Return first continuation reference in a chain of search results. 


e Idap_count_entries( -- Return number of entries in a chain of search results. 
e idap_msgfree(Q) -- Free LDAP result message. 

e Idap_search_sQ -- Synchronously search the directory. 

e Idap_searchQ -- Asynchronously search the directory. 


e Idap_search_ext() -- Asynchronously search the directory with controls. 


e Idap_search_st() -- Synchronously search the directory with timeout. 


The Idap_search_ext_s() API supports LDAP V3 server controls, client controls, and allows varying size 
and time limits to be easily specified for each search operation. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_search_s()--Perform an LDAP Search 
Operation (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_search_s ( 
LDAP *k1d, 
const char *base, 
int SCOpe, 
const char *filter, 
char **x*attrs, 
int attrsonly, 
LDAPMessage **res) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_search_s() function is used to perform a synchronous LDAP search operation. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or 
Idap_open(Q). 

base 
(Input) Specifies the DN of the entry at which to start the search. 

scope 
(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the object 
itself), or LDAP_SCOPE_ONELEVEL (to search the object's immediate children), or 
LDAP_SCOPE_SUBTREE (to search the object and all its descendents). 

filter 


(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be 
specified as attributetype=attributevalue. More complex filters are specified using a prefix notation 
according to the following BNF: 


<filter> ::= '(' <filtercomp> ')' 


<filtercomp> ::= <and> | <or> | <not> | <simple> 


<and> ::= '&' <filterlist> 
<or> sca T|" 2filterlist> 
<not> 2:= '!' <filter> 
“filterlist> <= <filters | <filter> <filterlist> 
<simple> ::= <attributetype> <filtertype> <attributevalue> 
<filtertype> ::= '=' | a= | "<=! | '>=! 
The '~=' construct is used to specify approximate matching. The representation for <attributetype> 


and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): 
Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute 
existence test, or can contain text and *'s interspersed to achieve substring matching. 


For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter 
"(mail=* @student.of.life.edu)" will find any entries that have a mail attribute ending in the specified 
string. 


More complex filters are created using the & and | operators. For example, the filter 
"(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail 
attribute. To put parentheses or asterisks in a filter, escape them with a backslash ‘\' character. See 
RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of 
allowable filters. 


attrs 
(Input) Specifies a null-terminated array of character string attribute types to return from entries that 
match filter. If NULL is specified, all attributes will be returned. 

attrsonly 
(Input) Specifies attribute information. Aftrsonly should be set to 1 to request attribute types only. Set 
to 0 to request both attributes types and attribute values. 

res 


(Output) Contains the result of the synchronous search operation. This result should be passed to the 
LDAP parsing routines (see ldap_first_entryQ, ldap_next_entry(), and so on). The caller is 


responsible for freeing res with ldap_msgfree(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. The code can be interpreted by Idap_perror() or ldap_err2string(). 


Error Conditions 


If ldap_search_s() is not successful, an error code will be returned. See LDAP Client API Error Conditions 
for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_search_s API. 


Related Information 


e Idap_first_entryQ -- Retrieve first LDAP entry. 


e idap_first_reference() -- Return first continuation reference in a chain of search results. 


e idap_count_entries() -- Return number of entries in a chain of search results. 
e idap_msgfree(Q) -- Free LDAP result message. 
e Idap_search() -- Asynchronously search the directory. 


e Idap_search_ext_s() -- Synchronously search the directory with controls. 


e idap_search_ext() -- Asynchronously search the directory with controls. 


e Idap_search_st() -- Synchronously search the directory with timeout. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_search_st()--Perform an LDAP Search 
Operation (Timed Synchronous) 


Syntax 


#include <sys/time.h> 
#include <ldap.h> 


int ldap_search_st ( 
LDAP *ld, 
const char *base, 
int Scope, 
const char *filter, 
char *xattrs, 
int attrsonly, 
struct timeval *timeout, 
LDAPMessage ** res) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_search_st() function is used to perform an LDAP search operation. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or 
Idap_open(). 

base 
(Input) Specifies the DN of the entry at which to start the search. 

scope 
(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the object 
itself), or LDAP_SCOPE_ONELEVEL (to search the object's immediate children), or 
LDAP_SCOPE_SUBTREE (to search the object and all its descendents). 

filter 


(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be 


specified as attributetype=attributevalue. More complex filters are specified using a prefix notation 
according to the following BNF: 


<filter> = '(' <filtercomp> ')' 
<filtercomp> ::= <and> | <or> | <not> | <simple> 
<and> = '&' <filterlist> 
<or> = 1|* <pilterlist> 
<not> = '!' <filter> 
<filterlist> «i= <filter> | <filter> <rilterlist> 
<simple> = <attributetype> <filtertype> <attributevalue> 
<filtertype> ::= '=' | t=! | <= | ot>=! 
The '~=' construct is used to specify approximate matching. The representation for <attributetype> 


and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): 
Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute 
existence test, or can contain text and *'s interspersed to achieve substring matching. 


For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter 
"(mail=* @ student.of.life.edu)" will find any entries that have a mail attribute ending in the specified 
string. 


More complex filters are created using the & and | operators. For example, the filter 
"(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail 
attribute. To put parentheses or asterisks in a filter, escape them with a backslash '‘\' character. See 
RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of 
allowable filters. 


attrs 
(Input) Specifies a null-terminated array of character string attribute types to return from entries that 
match filter. If NULL is specified, all attributes will be returned. 

attrsonly 
(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set 
to 0 to request both attributes types and attribute values. 

timeout 
(Input) The local search timeout value. 

res 


(Output) Contains the result of the synchronous search operation. This result should be passed to the 
LDAP parsing routines (see ldap_first_entryQ, ldap_next_entry(), and so on). The caller is 


responsible for freeing res with ldap_msgfree(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_search_st() is not successful, an error code will be returned. See LDAP Client API Error Conditions 
for possible LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_search_st API. 


Related Information 


e idap_first_entryQ -- Retrieve first LDAP entry. 


e ldap _first_reference() -- Return first continuation reference in a chain of search results. 


e Idap_count_entries() -- Return number of entries in a chain of search results. 
e idap_msgfree(Q) -- Free LDAP result message. 

e Idap_search_sQ -- Synchronously search the directory. 

e Idap_searchQ -- Asynchronously search the directory. 

e Idap_search_ext() -- Asynchronously search the directory with controls. 

e Idap_search_ext_sQ) -- Synchronously search the directory with controls. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_server_conf_save()-- Store Server 
Information into Local Configuration 


Syntax 


#include <ldap.h> 


typedef struct LDAP_Server_Info { 
char *1lsi_host; /* LDAP server's hostname */ 
unsigned short lsi_port; /* LDAP port ef: 
char *1lsi_suffix; /* Server's LDAP suffix */ 
char *1lsi_query_key; /* service_key[.edomain] */ 
char *1si_dns_domain; /* Publishing DNS domain */ 
int lsi_replica_type;/* master or replica * f: 
#define LDAP_LSI_MASTER 1 /* LDAP Master */ 
#define LDAP _LSI_REPLICA 2 /* LDAP Replica */ 
int lsi_sec_type; /* SSL or non-SSL * / 
#define LDAP_LSI_NOSSL 1 /* Non-SSL */ 
#define LDAP_LSI_SSL 2 /* Secure Server ff 
unsigned short lsi_priority; /* Server priority */ 
unsigned short lsi_weight; /* load balancing weight */ 
char *lsi_vendor_info; /* vendor information */ 
char *lsi_info; /* LDAP Info string */ 
struct LDAP_Server_Info *prev; /* linked list previous 
struct LDAP_Server_Info *next; /* linked list next ptr 
} LDAPServerInfo; 


int ldap_server_conf_save ( 
char * filename, 
unsigned long ttl, 
LDAPServerInfo *server_info_listp ); 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_server_conf_save() API is used to store server information for the local configuration. 


Authorities and Locks 


Object Authorities 


The caller must have Execute (*X) authority to each directory in the path name preceding the name 
of the configuration file. The caller must have Write (*W) authority to the configuration file. 


Parameters 


server_info_listp 


(input) A linked list of LDAPServerInfo structures. Each LDAPServerInfo structure defined in the 
list contains information on an LDAP server. This information will be stored in a file and can be 
retrieved using ldap_server_locate(). The LDAPServerInfo structure contains the following fields: 


lsi_host 
Isi_port 
lsi_suffix 


lsi_query_key 


lsi_dns_domain 


lsi_replica_type 


lsi_sec_type 


lsi_priority 


lsi_weight 


lsi_vendor_info 


lsi_info 


Fully-qualified hostname of the target server (NULL-terminated string). 
Integer representation of the LDAP server's port. 


String that specifies a supported suffix for the LDAP server 
(NULL-terminated string). 


Specifies the The eNetwork domain to which the LDAP server belongs, 
prefixed by the service key. For example, if service key is ldap and eNetwork 
domain is sales, then lsi_query_key would be set to Idap.sales. If the server is 
not associated with an eNetwork domain (as published in DNS), then 
lsi_query_key consists solely of the service key value. 


DNS domain in which the LDAP server was published. For example, the DNS 
search may have been for Idap.sales.tcp.austin.ibm.com, but the resulting 
server(s) has a fully-qualified DNS host name of Idap2.raleigh.ibm.com. In 
this example, lsi_host would be set to Idap2.raleigh.ibm.com whilst 
lsi_dns_domain would be set to austin.ibm.com. The actual domain in which 
the server was " published" may be of interest, particularly when multiple 
DNS domains are configured (or supplied as input). 


Specifies the type of server, LDAP_LSI_MASTER or LDAP_LSI_REPLICA. 
If set to zero, the type is unknown. 


Specifies the port's security type, LDAP_LSI_NOSSL or LDAP_LSI_SSL. 
This value is derived from the "Idap" or "Idaps" prefix on the LDAP URL. If 
the LDAP URL is not defined, the security type is unknown and Isi_sectype is 
set to zero. 


The priority value obtained from the SRV RR (or the "pseudo-SRV" TXT 
RR). Set to zero if unknown or notavailable. 


The weight value obtained from the SRV RR (or the "pseudo-SRV" TXT 
RR). Set to zero if unknown or not available. 


NULL-terminated string obtained from the ldapvendor TXT RR (if defined). 
May be used to identify the LDAP server vendor/version information. 


NULL-terminated information string obtained from the ldapinfo TXT RR (Gif 
defined). If not defined, lsi_info is set to NULL. This information string can 
be used by the LDAP or network administrator to publish additional 
information about the target LDAP server. 


filename 


(input) The configuration filename. Specify NULL to get the default filename, 
/QIBM/UserData/OS400/DirSrv/ldap_server_info.conf. 


ttl 


(input) Specifies the time-to-live (in minutes) for server information saved in the configuration file. 
Set ttl to zero if it is intended to be a permanent repository of information. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_server_conf_save() is not successful, an LDAP error code will be returned. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_server_conf_save API. 


Related Information 


e idap_init() -- Perform an LDAP initialization operation. 
e lidap_server_locate() -- Locate suitable LDAP servers. 
e idap_server_free_listQ -- Free the list of LDAP servers. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_server_free_list()-- Free the List of LDAP 
Servers 


Syntax 


#include <ldap.h> 


int ldap_server_free_list ( 
LDAPServeriInfo *server_info_listp ); 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_server_free_list() API is used to free the linked list of LDAPServerInfo structures (and all 
associated storage) as returned from the ldap_server_locate() API. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


server_info_listp 
(Input) The address of a linked list of LDAPServerInfo structures to be freed. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_server_free_list() is not successful, an error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_server_free_list API. 


Related Information 


e idap_server_conf_save() -- Store server information into local configuration. 


e |dap_server_locate() -- Locate suitable LDAP servers. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_server_locate()-- Locate Suitable LDAP 
Servers 


Syntax 


#include <ldap.h> 


typedef struct LDAP_Server_Request { 


int search_source; /* Source for server info */ 
#define LDAP_LSI_CONF_DNS 0 /* Config first, then DNS (def) */ 
#define LDAP _LSI_CONF_ONLY 1 /* Local Config file only */ 
#define LDAP_LSI_DNS_ONLY 2 /* DNS only a. 
char *conf_filename; /* pathname of config file ai): 
int reserved; /* Reserved, set to zero */ 
char *service_key; /* Service string */ 
char *enetwork_domain; /* eNetwork domain (eDomain) */ 
char *kname_servers; /* Array of name server addrs */ 
char **dns_domains; /* Array of DNS domains */ 
int connection_type; /* Connection type ef 
#define LDAP LSI _UDP_TCP 0 /* Use UDP, then TCP (default) */ 
#define LDAP _LSI_UDP 1 /* Use UDP only */ 
#define LDAP _LSI_TCP 2 /* Use TCP only */ 
int connection_timeout; /* connect timeout (seconds) */ 
char *DN_ filter; /* DN suffix filter */ 


unsigned char reserved2[64]; /* reserved fields, set to 0 */ 
} LDAPServerRequest; 


typedef struct LDAP_Server_Info { 


char *1lsi_host; /* LDAP server's hostname */ 

unsigned short lsi_port; /* LDAP port * / 

char *1lsi_suffix; /* Server's LDAP suffix */ 

char *1lsi_query_key; /* service_key[.edomain] */ 

char *1si_dns_domain; /* Publishing DNS domain */ 

int lsi_replica_type;/* master or replica * / 
#define LDAP _LSI_MASTER 1 /* LDAP Master */ 
#define LDAP _LSI_REPLICA 2 /* LDAP Replica xy 

int lsi_sec_type; /* SSL or non-SSL * / 
#define LDAP_LSI_NOSSL 1 /* Non-SSL */ 
#define LDAP_LSI_SSL 2 /* Secure Server * 

unsigned short lsi_priority; /* Server priority af 

unsigned short lsi_weight; /* load balancing weight */ 

char *lsi_vendor_info; /* vendor information */ 

char *lsi_info; /* LDAP Info string */ 

struct LDAP_Server_Info *prev; /* linked list previous ptr */ 

struct LDAP_Server_Info *next; /* linked list next ptr AT, 


} LDAPServeriInfo; 


int ldap_server_locate ( 
LDAPServerRequest *server_request, 


LDAPServeriInfo *kserver_info_listpp ); 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_server_locate() API is used to locate one or more suitable LDAP servers. In general, an 
application will use the Idap_server_locate() API as follows: 


e Prior to connecting to an LDAP server in the enterprise, use Idap_server_locate() to obtain a list of 
one or more LDAP servers that have been published in DNS (or in the local configuration file). 
Typically an application can simply use the default request settings (by passing a NULL for the 
LDAPServerRequest parameter). By default, the API will look for server information in the local 
configuration file first /QIBM/UserData/OS400/DirSrv/ldap_server_info.conf), then move on to 
DNS if the local configuration file doesn't exist (or has expired). 


e@ Once the application has obtained the list of servers, it should walk the list, using the first server 
that meets its needs. This will maximize the advantage that can be derived from using the priority 
and weighting scheme implemented by the administrator. The application may not want to use the 
first server in the list for several reasons: 


oO The client needs to specifically connect using SSL (or non-SSL). In this case, the server 
needs to walk the list until it finds a server entry with the appropriate type of security type. 
Note that an LDAP server may be listening on both an SSL and non-SSL port. In this case, 
the server will have two entries in the server list. 


oO The client specifically needs to connect to a Master (or Replica). 


o The client needs to connect to a server that supports a particular suffix. NOTE that the list 
of server's returned in the list can be filtered by specifying DN_filter, which filters out 
servers that do not have a suffix under which the DN resides. 


o There is some other characteristic associated with the desired server (perhaps defined in the 
Idapinfo string). 


e Once the client has selected a server, it then issues the ldap_initQ or ldap_ssl_initQ) API. If the 


selected server is unavailable, the application is free to move down the list of servers until it either 
finds a suitable server it can connect to, or the list is exhausted. 


Authorities and Locks 


Object Authorities 


The caller must have Execute (*X) authority to each directory in the path name preceding the name 
of the configuration file (/(QIBM/UserData/OS400/DirSrv). The caller must have Read (*R) 
authority to the configuration file (Idap_server_info.conf). 


Parameters 


server_request 


(Input) Specifies a pointer to an LDAPServerRequest structure. If the default behavior is desired 
for all possible input parameters, simply set server_request to NULL. Otherwise, supply the 
address of the LDAPServerRequest structure, which contains the following fields: 


search_source 


conf_filename 


service_key 


enetwork_domain 


Specifies where to find the server information. 


The options are: 


O First access the local LDAP DNS configuration file. If the file is 
not found, or the file does not contain information for a 
combination of the service_key, eDomain and any of the DNS 
domains (as specified by the application), then access DNS. 


oO Search the local LDAP DNS configuration file only. 
Oo Search DNS only. 


Specifies an alternative configuration filename. Specify NULL to use the 
default filename and location. 


Specifies the search key (that is, the service name string) to be used when 
obtaining a list of SRV, "pseudo-SRV TXT" or CNAME alias records 
from DNS. If not specified, the default is "Idap". Administrators are 
encouraged to use the ldap default when setting up information in DNS 
servers, to maximize a client application's ability to find LDAP servers 
that have been published in DNS. 


Indicates that LDAP servers belonging to the specified eNetwork domain 
are to be located. The criteria for searching DNS to locate the appropriate 
LDAP server(s) is constructed by concatenating the following 
information: 


oO search_key (defaults to ldap) 
Oo enetwork_domain 
o DNS domain 
Oo "tep" 
For example, if: 
oO The default search_key of ldap is used 
o The eNetwork domain is sales5 
o The client's default DNS domain is midwest.acme.com 


Then the DNS "value" used to search DNS for the set of LDAP servers 
belonging to the sales5 domain is Idap.sales5.midwest.acme.com.tcp. 


name_servers 


dns_domains 


If enetwork_domain is set to zero, the following steps are taken to 
determine the enetwork_domain: 


oO The locally configured default, if set, will be used (as set with the 
o Idap_enetwork_ domain_set() API). 


o Ifa locally configured default is not set, then a platform-specific 
value is used. On Windows NT, the user's logon domain is used. 


o Ifa platform-specific eNetwork domain is not defined, then the 
eNetwork domain component in the DNS "value" is omitted. In 
the above example, this would result in the following string being 
used: Idap.midwest.acme.com.tcp. 


If enetwork_domain is set to a NULL string, then the eNetwork domain 
component in the DNS "value" is omitted. This might be useful for finding 
a default eNetwork domain (when a specific edomain name is not known). 


Specifies an array of one or more string representations of DNS name 
server IP address (in dotted decimal format; for example, 
"122.122.33.49"). If not specified, the locally configured DNS name 
server(s) will be used. 


Specifies an array of one or more DNS domain names. If not specified, the 
local DNS domain configuration is used. 
Note that domain names supplied here can take the following forms: 

Oo austin.ibm.com (standard DNS format) 

o cn=fred, ou=accounting, dc=austin, dc=ibm, dc=com 
With respect to providing a domain name, these are equivalent. Both result 
in a domain name of "austin.ibm.com". This approach makes it easier for 


an application to locate LDAP servers to which it needs to bind (based on 
a user name space mapped into the DNS name space). 


DNS DOMAINS and CONFIGURATION FILE 
The local configuration file may contain server information for 
combinations of the following: 

oO Service key (typically set to Idap) 

o eNetwork domain 

oO DNS domains 
When the application sets search_source to LDAP_LSI_CONFIG_DNS, 
the Idap_server_locate() API will attempt to find server information in the 


configuration file for the designated service key, eNetwork domain and 
DNS domain(s). 


If the configuration file does not contain information that matches this 
criteria, the locator API will search DNS, using the specified service key, 
eNetwork domain and DNS domain(s). For example: 


oO The application supplies the following three DNS domains: 
m austin.ibm.com 
m raleigh.ibm.com 


= miami.ibm.com 


connection_type 


connection_timeout 


DN_filter 


o plus, the application uses the default service key (that is, ldap and 
specifies sales for the eNetwork domain). 


oO The configuration file contains server information for 
austin.ibm.com and miami.ibm.com (with the default service key 
and eNetwork domain of sales). 


oO. The search_source parameter is set to 
LDAP_LSI_CONFIG_DNS, which indicates that both the 
configuration file and DNS are to be used if necessary. 


oO The locator API will build a single ordered list of server entries, 
with the following: 


m Server entries for the austin.ibm.com DNS domain, as 
extracted from the configuration file. 


m Server entries for the raleigh.ibm.com DNS domain, as 
obtained from DNS over the network. 


m Server entries fo rthe miami.ibm.com DNS domain, as 
extracted from the configuration file. 


In other words, the resulting list of servers will contain all the 
austin.ibm.com servers first, followed by the raleigh.ibm.com servers, 
followed by the miami.ibm.com servers. Within each grouping of servers 
(by DNS domain), the entries are sorted by priority and weight. 


Specifies the type of connection to use when communicating with the 
DNS name server. The following options are supported: 


o Use UDP first. It no response is received, or data truncation 
occurs, then use TCP. 


o Only use UDP. 
Oo Only use TCP. 


If set to zero, the default is to use UDP first (then TCP). 


UDP is the preferred connection type, and typically performs well. You 
might want to consider using TCP/IP if: 


Oo The amount of data being returned will not fit in the 512-byte 
UDP packet. 


oO The transmission and receipt of UDP packets turns out to be 
unreliable. This may depend on network characteristics. 


Specifies a timeout value when querying DNS (for both TCP and UDP). If 
LDAP_LSI_UDP_TCP is specified for connection_type and a response is 
not received in the specified time period for UDP, TCP will be attempted. 
A value of zero results in an infinite timeout. When the 
LDAPServerRequest parameter is set to NULL, the default is ten seconds. 
When passing the LDAPServerRequest parameter, this parameter should 
be set to a non-zero value if an indefinite timeout is not desired. 


Specifies a Distinguished Name to be used as a filter, for selecting 
candidate LDAP servers based on the server's suffix (or suffixes). If the 
most significant portion of the DN is an exact match with a server's suffix 
(after normalizing for case), an LDAPServerInfo structure is returned for 
the server/suffix combination. If it doesn't match, an LDAPServerInfo 
structure is not returned for the server/suffix combination. 


reserved2 Represents a reserved area for future function, which should be initialized 
to zero. 


server_info_listpp 


(output) Specifies the address that will be set to point to a linked list of LDAPServerInfo structures. 
Each LDAPServerlInfo structure defined in the list contains server information obtained from 
either: 


o DNS 
o Local configuration 


Upon successful return from Idap_server_locate(), server_info_listpp points to a linked list of 
LDAPServerlInfo structures. The LDAPServerInfo structure (as defined above), contains the 


following fields: 
Isi_host Fully-qualified hostname of the target server (NULL-terminated string). 
Isi_port Integer representation of the LDAP server's port. 
Isi_suffix String that specifies a supported suffix for the LDAP server 


(NULL-terminated string). 


Isi_query_key Specifies the The eNetwork domain to which the LDAP server belongs, 
prefixed by the service key. For example, if service key is ldap and eNetwork 
domain is sales, then lsi_query_key would be set to Idap.sales. If the server is 
not associated with an eNetwork domain (as published in DNS), then 
lsi_query_key consists solely of the service key value. 


lsi_dns_domain DNS domain in which the LDAP server was published. For example, the DNS 
search may have been for Idap.sales.tcp.austin.ibm.com, but the resulting 
server(s) has a fully-qualified DNS host name of Idap2.raleigh.ibm.com. In 
this example, lsi_host would be set to Idap2.raleigh.ibm.com whilst 
lsi_dns_domain would be set to austin.ibm.com. The actual domain in which 
the server was "published" may be of interest, particularly when multiple 
DNS domains are configured (or supplied as input). 


lsi_replica_type Specifies the type of server, LDAP_LSI_MASTER or LDAP_LSI_REPLICA. 
If set to zero, the type is unknown. 


Isi_sec_type Specifies the port's security type, LDAP_LSI_NOSSL or LDAP_LSI_SSL. 
This value is derived from the "Idap" or "Idaps" prefix on the LDAP URL. If 
the LDAP URL is not defined, the security type is unknown and Isi_sectype is 
set to zero. 


lsi_priority The priority value obtained from the SRV RR (or the "pseudo-SRV" TXT 
RR). Set to zero if unknown or not available. 


Isi_weight The weight value obtained from the SRV RR (or the "pseudo-SRV" TXT 
RR). Set to zero if unknown or not available. 


lsi_vendor_info _NULL-terminated string obtained from the Idapvendor TXT RR (if defined). 
May be used to identify the LDAP server vendor/version information. 


lsi_info NULL-terminated information string obtained from the ldapinfo TXT RR (Gif 
defined). If not defined, Isi_info is set to NULL. This information string can 
be used by the LDAP or network administrator to publish additional 
information about the target LDAP server. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


If ldap_server_locate() is not successful, an error code will be returned. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_server_locate API. 


Related Information 


e |dap_init() -- Perform an LDAP initialization operation. 


e Idap_server_conf_save() -- Store server information into local configuration. 


e ldap_server_free_listQ -- Free the list of LDAP servers. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_set_iconv_local_charset()-- Set the Active 
LDAP Character Set 


Syntax 


#include <ldap.h> 


int 
ldap_set_iconv_local_charset ( char *charset ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_set_iconv_local_charset() API checks if the character set is supported. If supported, the API 
calls Idap_set_iconv_local_codepage() to set the global variable /dap_global_codepage to a corresponding 


codepage value. 


A limited set of the IANA character sets will be supported. Character sets supported include: 


Character Set Name Locale Codepage 


ISO-8859-1 EN_US 819 
ISO-8859-2 HU_HU 912 
ISO-8859-5 RU_RU- 915 
ISO-8859-6 AR_AA _— 1089 
ISO-8859-7 EL GR 813 
ISO-8859-8 IW_IL 916 
ISO-8859-9 TR_TR = 920 
IBM437 n/a 437 
IBM850 EN_US 850 
IBM852 n/a 852 
IBM857 n/a 857 
IBM862 n/a 862 
IBM864 n/a 864 
IBM866 n/a 866 


IBM869 n/a 869 


TIS-620 TH_TH 874 
EUC-JP JA_JP 954 
EUC-KR KO_KR 970 
EUC-CN ZN_CN 1383 
EUC-TW ZH_TW 964 
Shift-JIS JAJP —-932 
GBK ZH_CN 1386 
Bigs ZH_TW 950 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


charset 


(input) specifies character set value. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


Other LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_set_iconv_local_charset() API returns an LDAP error code if not successful. See LDAP Client 
API Error Conditions for possible values for LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_set_iconv_local_charset API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert String From the Local to UTF-8 Code Page. 


e Idap_xlate_utf8_to_local(Q -- Convert String From UTF-8 to Local Code Page. 
e Idap_xlate_local_to_unicode() -- Convert String From the Local to UCS-2 Code Page. 
e Idap_xlate_unicode_to_local(Q) -- Convert String From UCS-2 to Local Code Page. 


e Idap_get_iconv_local_codepage() -- Get the Active LDAP Code Page. 


e Idap_set_iconv_local_codepage() -- Set the Active LDAP Code Page. 
e idap_set_locale() -- Change the Locale Used by LDAP. 
e Idap_get_locale( -- Get the Locale Used by LDAP. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_set_iconv_local_codepage() -- Set the 
Active LDAP Code Page 


Syntax 


#include <ldap.h> 


int 
ldap_set_iconv_local_codepage ( char *codepage ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_set_iconv_local_codepage() API is used to set a global variable, /dap_global_codepage, to a 
value passed by codepage or to a value associated with a locale if codepage is NULL. 


NOTE that the word local in the API refers to the value of the global variable /dap_global_codepage if it is 
set or a codepage value associated with the current locale. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


codepage 


(input) specifies local code page value. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


Other LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_set_iconv_local_codepage() API will return an LDAP error code if not successful. See LDAP 
Client API Error Conditions for possible values for LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_set_iconv_local_codepage API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert string from the local to UTF-8 code page. 
e Idap_xlate_utf8_to_local(Q -- Convert string from UTF-8 to local code page. 


e Idap_xlate_local_to_unicode() -- Convert string from the local to UCS-2 code page. 


e Idap_xlate_unicode_to_local() -- Convert string From UCS-2 to local code page. 


e Idap_get_iconv_local_codepage() -- Get the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


Idap_set_locale(Q) -- Change the locale used by LDAP. 
e Idap_get_localeQ -- Get the locale used by LDAP. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_set_Iderrno() -- Set Error Information 


Syntax 


#include <ldap.h> 


int ldap_set_lderrno ( 
LDAP * 1d; 
int error, 
const char *dn, 
const char *errmsg ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_set_Iderrno() function sets an error code and other information about an error in the specified 
LDAP structure. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

error 
(Input) The LDAP error code to be set in the /d. 

dn 
(Input) The distinguished name (DN) that identifies an existing entry. Normally, it is used to 
indicate how much of the name in the request is recongnized by a server on an 
LDAP_NO_SUCH_OBJECT error. However, in this case since it is an input to this API it should 
be a DN consistent with the error and errmsg parameters input on this API. 

errmsg 


(Input) The text of the error message, as if returned from a server. 


Return Value 


LDAP error code 
See LDAP Client API Error Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_set_lderrno API. 


Related Information 


e ldap_err2stringQ -- Convert LDAP error indication to a string. 
e |dap_perror( -- Print an LDAP error indication to standard error. 
e Idap_get_errno() -- Obtain information from most recent error. 


e Idap_get_Iderrno() -- Retrieve Error Information 


e Idap_result2error() -- Extract LDAP error indication from LDAP result. 


API introduced: V5R1 


Top | Directory Services APIs | APIs by category 


Idap_set_locale() -- Change the Locale Used by 
LDAP 


Syntax 


#include <ldap.h> 


int ldap_set_locale ( 
char 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: No 


The Idap_set_locale() API is used to change the locale used by LDAP for conversions between the local 
code page and UTF-8 or Unicode. Unless explicitly set with the Idap_set_locale() API, LDAP will use the 
application's default locale. To force the LDAP library to use another locale, specify the appropriate locale 
string. 


Note that the specified locale is applicable to all conversions by the LDAP library within the applications 
address space. The LDAP locale should be set or changed only when there is no other LDAP activity 
occuring within the application on other threads. 


Authorities and Locks 


*R authority is needed to the selected locale file and *X to the associated directories. 


Parameters 


locale 


(Input) The locale to be used by LDAP when using conversion apis to convert local text to/from 
UTF-8 or Unicode. If the locale is not explicitly set, the LDAP library will use the application's 
default locale. To force the LDAP library to use another locale, specify the appropriate locale 
string. 


You can set the value of locale to C, "", LC_C or the IFS pathname of a *LOCALE object. A 
locale value of C indicates the default C environment. A locale value of "" tells Idap_set_locale() 
to use the default locale for the implementation. 


Examples: 


re ldap_set_locale(LC_C); 


ldap_set_locale("/qsys.lib/en_us.locale"); 


re 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_set_locale() API will return LDAP error code if not successful. See LDAP Client API Error 
Conditions for possible values for LDAP error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_set_locale API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert string from the local to UTF-8 code page. 


e Idap_xlate_utf8_to_local(Q) -- Convert string From UTF-8 to local code page. 


e Idap_xlate_local_to_unicode() -- Convert string from the local to UCS-2 code page. 


e Idap_xlate_unicode_to_local() -- Convert string from UCS-2 to local code page. 
Idap_get_iconv_local_codepage() -- Get the active LDAP code page. 


e idap_set_iconv_local_codepage() -- Set the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


e Idap_get_localeQ -- Get the locale used by LDAP. 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_set_option() -- Set LDAP Options 


Syntax 


#include <ldap.h> 


int ldap_set_option ( 
LDAP *k1ld, 
int optionToSet, 
const void *optionValue ) 


Library Name/Service Program: QSYS/QGLDCLNT 


Default Public Authority: *USE 


Threadsafe: Yes 


The Idap_set_option() function is used to set options for the specified LDAP connection. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) An LDAP pointer returned by a previous call to Idap_initQ, Idap_ssl_initQ, or Idap_open(Q). 
If a NULL /d is passed in, the default option value is set. Later calls to ldap_initQ, ldap_ssl_initQ, 
or Idap_openQ) will use the set value as the default for the option. 


optionToSet 
(Input) The option value to be set. See below for the list of supported options. 


option Value 


(Input) The address of the value. For LDAP V3 client options, optionValue is the actual value to be 
set. 


The following session settings can be set using the Idap_set_option() API: 


LDAP_OPT_SIZELIMIT Mmaximum number of entries that can be returned on a search 
operation 


LDAP_OPT_TIMELIMIT Maximum number of seconds to wait for search results 


LDAP_OPT_REFHOPLIMIT Maximum number of referrals in a sequence that the client can 


follow 
LDAP_OPT_DEREF Rules for following aliases at the server 
LDAP_OPT_REFERRALS Whether referrals should be followed by the client 
LDAP_OPT_DEBUG Client debug options 
LDAP_OPT_SSL_CIPHER SSL ciphers to use 
LDAP_OPT_SSL_TIMEOUT SSL timeout for refreshing session keys 
LDAP_OPT_REBIND_FN Address of application's setrebindproc procedure 


LDAP_OPT_PROTOCOL_VERSION LDAP protocol version to use (V2 or V3) 
LDAP_OPT_SERVER_CONTROLS Default server controls. 
LDAP_OPT_CLIENT_CONTROLS Default client library controls 
LDAP_OPT_UTF&_IO String Data type UTF-8 option 


The value returned by Idap_get_option() when LDAP_OPT_PROTOCOL_VERSION is specified can be 


used to determine how parameters should be passed to the Idap_set_option() call. The easiest way to work 
with this compatibility feature is to guarantee that calls to Idap_set_option() are all performed while the 
LDAP_OPT_PROTOCOL_VERSION is set to the same value. If this cannot be guaranteed by the 
application, then follow the format of the example below when coding the call to Idap_set_option(): 


int sizeLimit=100; 
int protocolVersion; 
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &protocolVersion ); 
if ( protocolVersion == LDAP_VERSION2 ) { 
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit ); 
} else { /* the protocol version is LDAP_VERSION3 */ 


ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizeLimit ); 
} 


Additional details on specific options for Idap_set_option() are provided in the following sections. 


LDAP_OPT_SIZELIMIT 


Specifies the maximum number of entries that can be returned on a search operation. Note: the actual size 
limit for operations is also bounded by the maximum number of entries that the server is configured to 
return. Thus, the actual size limit will be the lesser of the value specified on this option and the value 
configured in the LDAP server. The default sizelimit is unlimited, specified with a value of zero (thus 
deferring to the sizelimit setting of the LDAP server). 


Examples: 


sizevalue=50; 


ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue) ; 
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue) ; 


LDAP_OPT_TIMELIMIT 


Specifies the number of seconds to wait for search results. Note: the actual time limit for operations is also 
bounded by the maximum time that the server is configured to allow. Thus, the actual time limit will be the 
lesser of the value specified on this option and the value configured in the LDAP server. The default is 
unlimited (specified with a value of zero). 


Examples: 


timevalue=50; 
ldap_set_option( ld, LDAP_OPT_TIMELIMIT, é&timevalue) ; 
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, é&timevalue) ; 


LDAP_OPT_REFHOPLIMIT 


Specifies the maximum number of hops that the client library will take when chasing referrals. The default 
is 5. 


Examples: 


hoplimit=7; 
ldap_set_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit) ; 
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit); 


LDAP_OPT_DEREF 


Specifies alternative rules for following aliases at the server. The default is LDAP_DEREF_NEVER. 
Supported values: 

0 LDAP_DEREF_NEVER 

I LDAP_DEREF_SEARCHING 

2 LDAP_DEREF_FINDING 

3 LDAP_DEREF_ALWAYS 


Examples: 


int deref = LDAP_DEREF_NEVER; 
ldap_set_option( ld, LDAP_OPT_DEREF, éderef) ; 
ldap_get_option( ld, LDAP_OPT_DEREF, &deref); 


LDAP_OPT_REFERRALS 


Specifies whether the LDAP library will automatically follow referrals returned by LDAP servers or not. It 
can be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. By default, the LDAP client 
will follow referrals. 


Examples: 


int value; 
ldap_set_option( ld, LDAP_OPT_REFFERALS, (void *) LDAP_OPT_ON) ; 
ldap_get_option( ld, LDAP_OPT_REFFERALS, é&value); 


LDAP_OPT_DEBUG 


Specifies a bit-map that indicates the level of debug trace for the LDAP library. 

Supported values: 
/* Debug levels */ 
LDAP_DEBUG_OFF 0x000 
LDAP_DEBUG_TRACE 0x001 
LDAP_DEBUG_PACKETS 0x002 
LDAP_DEBUG_ARGS 0x004 
LDAP_DEBUG_CONNS 0x008 
LDAP_DEBUG_BER 0x010 
LDAP_DEBUG_FILTER 0x020 
LDAP_DEBUG_CONFIG — 0x040 
LDAP_DEBUG_ACL 0x080 
LDAP_DEBUG_STATS 0x100 
LDAP_DEBUG_STATS2 0x200 
LDAP_DEBUG_SHELL 0x400 
LDAP_DEBUG_PARSE 0x800 
LDAP_DEBUG_ANY Oxffff 


Examples: 


int value; 

int debugvalue= LDAP_DEBUG_TRACE | LDAP _DEBUG_ PACKETS; 
ldap_set_option( ld, LDAP_OPT_DEBUG, &debugvalue) ; 
ldap_get_option( ld, LDAP_OPT_DEBUG, &value ); 


An alternative way to set the debug level is to set the LDAP_DEBUG environment variable in the job that 
the client application will run in. The environment variable is set to the same numerical value that the value 
variable would be set to if Idap_set_option() was used. An example of enabling client trace for an 
application using the LDAP_DEBUG environment variable: 


ADDENVVAR ENVVAR (LDAP_DEBUG) VALUE (0X0003) 


After the client application has run, use 


DMPUSRTRC Jjobnumber-of-the-client—job 


Then, to display the trace information interactively, use 


DSPPFM QAPOZDMP QPOZnnnnnn -—- where nnnnnn is the job number. 


LDAP_OPT SSL_CIPHER 


Specifies a set of one or more ciphers to be used when negotiating the cipher algorithm with the LDAP 
server. The first cipher in the list that is common with the list of ciphers supported by the server is chosen. 
For the export version of the library, the value used is "0306". For the domestic version of the library, the 
default value is "05040A090306". Note that the cipher string supported by the export version of the LDAP 
client library is fixed and cannot be modified. 


Supported ciphers: 


LDAP_SSL_RC4_MD5_EX 03 


LDAP_SSL_RC2_MD5_EX 05 (Non-export only) 
LDAP_SSL_RC4_SHA_US 04 (Non-export only) 


LDAP_SSL_RC4_MD5_US 06 


LDAP_SSL_DES_SHA_US 09 (Non-export only) 


LDAP_SSL_3DES_SHA_US — 0A (Non-export only) 


=» LDAP_SSL_AES_SHA_US  2F (Non-export only)*& 


Examples: 


char *setcipher = "2F090A"; 

char *getcipher; 

ldap_set_option( 1d, LDAP_OPT_SSL_CIPHER, setcipher); 
ldap_get_option( ld, LDAP_OPT_SSL_CIPHER, &getcipher ); 


LDAP_OPT_SSL_TIMEOUT 


Specifies in seconds the SSL inactivity timer. After the specified seconds, in which no SSL activity has 
occurred, the SSL connection will be refreshed with new session keys. A smaller value may help increase 
security, but will have a small impact on performance. The default SSL timeout value is 43200 seconds. 


Examples: 


value = 100; 
ldap_set_option( ld, LDAP_OPT_SSL_TIMEOUT, &value ) 
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &value ) 


tf 
, 


LDAP_OPT_REBIND_FN 


Specifies the address of a routine to be called by the LDAP library when the need arises to authenticate a 
connection with another LDAP server. This can occur, for example, when the LDAP library is chasing a 
referral. If a routine is not defined, referrals will always be chased using the anonymous identity. A default 
routine is not defined. 


Examples: 


extern LDAPRebindProc proc_address; 

LDAPRebindProc value; 

ldap_set_option( ld, LDAP_OPT_REBIND_FN, &proc_address) ; 
ldap_get_option( ld, LDAP_OPT_REBIND_FN, é&value); 


LDAP_OPT_PROTOCOL_VERSION 


Specifies the LDAP protocol to be used by the LDAP client library when connecting to an LDAP server. 
Also used to determine which LDAP protocol is being used for the connection. For an application that uses 
ldap_init() to create the LDAP connection the default value of this option will be LDAP_VERSION3 for 
communicating with the LDAP server. The default value of this option will be LDAP_VERSION2 if the 
application uses the deprecated ldap_open() API. In either case, the 
LDAP_OPT_PROTOCOL_VERSION option can be used with Idap_set_option() to change the default. 
The LDAP protocol version should be reset prior to issuing the bind (or any operation that causes an 
implicit bind). 


Examples: 


version2 = LDAP_VERSION2; 

version3 = LDAP_VERSION3; 

/* Example for Version 3 application setting version to version 2 */ 
ldap_set_option( 1d, LDAP_OPT_PROTOCOL_VERSION, é&version2); 

/* Example of Version 2 application setting version to version 3 */ 
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version3); 
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, é&value) ; 


LDAP_OPT_SERVER_CONTROLS 


Specifies a default list of server controls to be sent with each request. The default list can be overridden by 
specifying a server control, or list of server controls, on specific APIs. By default, no server controls will be 
sent. 


Example: 


ldap_set_option( 1d, LDAP_OPT_SERVER_CONTROLS, &ctrlp)j; 


LDAP_OPT_CLIENT_CONTROLS 


Specifies a default list of client controls to be processed by the client library with each request. Since client 
controls are not defined for this version of the library, the lIdap_set_option() API can be used to define a set 
of default, non-critical client controls. If one or more client controls in the set is critical, the entire list is 
rejected with a return code of LDAP_UNA VAILABLE_CRITICAL_EXTENSION. 


LDAP_OPT_UTF8 _ IO 


Specifies whether the LDAP library will automatically convert string data to and from the local code page. 
It can be set to one of the constants LDAP_UTF8_XLATE_ON or LDAP_UTF8_XLATE_OFF. By 
default, the LDAP library will convert string data. 


When conversion is disabled, the LDAP library assumes that data received from the application by LDAP 
APIs is already represented in UTF-8. Similarly, the LDAP library assumes that the application is prepared 
to receive string data from the LDAP library represented in UTF-8 (or as binary). 


When LDAP_UTF8_XLATE_ON is set (the default), the LDAP library assumes that string data received 
from the application by LDAP APIs is in the default (or explicitly designated) code page. Similarly, all 
string data returned from the LDAP library (back to the application) is converted to the designated local 
code page. 


It is important to note that only string data supplied on connection-based APIs will be translated (that is, 
only those APIs that include an Id will be subject to translation). For example, string values passed in to 
ldap_searchQ) will be converted, but string values passed in to ldap_init will not. 


It is also important to note that translation of strings from a UTF-8 encoding to local code page may result 
in loss of data when one or more characters in the UTF-8 encoding cannot be represented in the local code 
page. When this occurs, a substitution character replaces any UTF-8 characters that cannot be converted to 
the local code page. 


For more information on explicitly setting the locale for conversions, see ldap_set_locale(). 


Examples: 


int value; 
ldap_set_option( ld, LDAP_OPT_UTF8_IO, (void *) LDAP_UTF8_XLATE_ON) ; 
ldap_get_option( ld, LDAP_OPT_UTF8_I0O, é&value); 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_set_option() function will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error codes values. 


Error Messages 


The following message may be sent from this function. 
Message ID _ Error Message Text 


CPF3CF2 E_ Error(s) occurred during running of Idap_set_option API. 


Related Information 


e Idap_get_option( -- Retrieve an option associated with an LDAP descriptor. 


e ldap init() -- Initializes a session with an LDAP server. 


e idap_open(Q) -- Open a connection to an LDAP server (deprecated). 
e Idap_set_rebind_proc() -- Set rebind procedure 


e idap_versionQ -- Obtain LDAP version and SSL cipher information. 
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Idap_set_rebind_proc()--Set Rebind Procedure 


Syntax 


#include <ldap.h> 
void ldap_set_rebind_proc ( 


LDAP *ld, 
LDAPRebindProc rebindproc ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_set_rebind_proc() function is used to set the entry-point of a routine that will be called back to 
obtain bind credentials for use when a new server is contacted during the following of an LDAP referral. 
Note that this function is only useful when the LDAP_OPT_REFERRALS option is set (this is the 
default). If ldap_set_rebind_proc() is never called, or if it is called with a NULL rebindproc parameter, an 
unauthenticated simple LDAP bind will always be done when chasing referrals. 


rebindproc should be a function that is declared like this: 


int rebindproc( LDAP *ld, char **whop, char **credp, 
int *methodp, int freeit ); 


The LDAP library will first call the rebindproc to obtain the referral bind credentials, and the freeit 
parameter will be zero. The function must set whop, credp, and methodp as appropriate. If the rebindproc 
returns LDAP_SUCCESS, referral processing continues, and the rebindproc will be called a second time 
with freeit non-zero to give your application a chance to free any memory allocated in the previous call. 


If anything but LDAP_SUCCESS is returned by the first call to the rebindproc, referral processing is 
stopped and that error code is returned for the original LDAP operation. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 
rebindproc 


(Input) Specifies the entry-point of a routine that will be called to obtain bind credentials used when 


a new server is contacted during the following of an LDAP referral. 


Return Value 


None 


Error Conditions 


The Idap_set_rebind_proc() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_set_rebind_proc API. 


Related Information 


e idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 
e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 


e idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 


e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 
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Idap_simple_bind()--Perform a Simple LDAP 
Bind Request 


Syntax 


#include <ldap.h> 


int ldap_simple_bind ( 
LDAP *1d, 
const char *dn, 
const char *passwd ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_simple_bind() function is used to authenticate a distinguished name (DN) to a directory server. 


For LDAP V2 servers, after a connection is made to an LDAP server by using the Idap_openQ), Idap_initQ, 
or Idap_ssl_initQ APIs, an LDAP bind API must be called before any other LDAP APIs can be called for 
that connection. For LDAP V3 servers, the bind is optional. 


Idap_simple_bind() is an asynchronous request. The result of the operation can be obtained by a 
subsequent call to Idap_result(). 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


ld 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 
(Input) Specifies the Distinguished Name of the entry to bind as. 
passwd 


(Input) Specifies the password used in association with DN of the entry in which to bind. 


Return Value 


Message ID of the Operation Initiated 
if the request was successful. A subsequent call to Idap_result(), can be used to obtain the result. 


-1 


if the request was not successful, setting the session error parameters in the LDAP structure 
appropriately, which can be obtained by using Idap_get_Iderrno(). 


Error Conditions 


If Idap_simple_bind() is not successful, -1 will be returned setting the session error (/d_errno) parameters 
in the LDAP structure appropriately. See LDAP Client API Error Conditions for possible LDAP error code 


values. Use ldap_get_Iderrno() to obtain the error code /d_errno. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_simple_bind API. 


Related Information 


e idap_bindQ -- Asynchronously bind to the directory (deprecated). 

e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 

e idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 

e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 

e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 
e idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


e idap_set_rebind_proc() -- Sets the entry-point of a routine during the chasing of referrals. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_simple_bind_s()--Perform a Simple LDAP 
Bind Request (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_simple_bind_s ( 
LDAP *id, 
const char *dn, 
const char *passwad) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_simple_bind_s() function is used to authenticate a distinguished name (DN) to a directory server. 


For LDAP V2 servers, after a connection is made to an LDAP server by using the Idap_open(Q), Idap_initQ, 
or Idap_ssl_initQ) APIs, an LDAP bind API must be called before any other LDAP APIs can be called for 
that connection. For LDAP V3 servers, the bind is optional. 


Idap_simple_bind_s() performs a synchronous request. 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 


dn 
(Input) Specifies the Distinguished Name of the entry to bind as. 
passwd 


(Input) Specifies the password used in association with DN of the entry in which to bind. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


If Idap_simple_bind_s() is not successful, it returns an LDAP error code. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_simple_bind_s API. 


Related Information 


e idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 
e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 

e Idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 
e idap_set_rebind_proc() -- Sets the entry-point of a routine during the chasing of referrals. 
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Idap_ssl_client_init --Initializes the SSL Library. 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


int ldap_ssl_client_init ( 
char *keyring, 
char *keyring_pw, 
int ssl_timeout, 
int *oSSLReasonCode) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDCLNT 


Threadsafe: Yes 


The Idap_ssl_client_init() routine is used to initialize the SSL protocol stack for an application process. It 
should be called once, prior to making any other LDAP calls. Once Idap_ssl_client_init() has been successfully 
called, any subsequent invocations will return a return code of LDAP_SSL_ALREADY_INITIALIZED. 


A related API, Idap_app_ssl_client_init_npQ is available for using Digital Certificate Manager (DCM) 


Application IDs when authenticating the client to the server. Either Idap_ssl_client_init() or 
Idap_app_ssl_client_init_npQ (but not both) can be called in an application process. 


Although still supported, the use of the Idap_ssl_start() API is now deprecated. The Idap_ssl_client_init() and 
Idap_ssl_initQ) or Idap_app_ssl_client_init_npQ and Idap_app_ssl_init_npQ APIs should be used instead. 


Authorities and Locks 


Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated directories. 


Parameters 


keyring 


(Input) Specifies the name of a key database file (with "kdb" extension). The key database file typically 
contains one or more certificates of certification authorities (CAs) that are trusted by the client. These 
types of X.509 certificates are also known as trusted roots. A key database can also be used to store the 
client's private key(s) and associated client certificate(s). A private key and associated client certificate 
are required only if the LDAP server is configured to require client and server authentication. If the 
LDAP server is configured to provide only server authentication, a private key and client certificate are 
not required. 


A fully-qualified path and filename is recommended. If a filename without a fully-qualified path is 
specified, the LDAP library will look in the current directory for the file. The key database file 
specified here must have been created using the Digital Certificate Manager (DCM). If a key database 
is not supplied, keyring is null, the *SYSTEM Certificate Store is used. 


keyring_pw 
(Input) Specifies the password that is used to protect the contents of the key database. This password is 


important since it protects the private key stored in the key database. The password was specified when 
the key database was initially created. A NULL pointer to the password is accepted. 


ssl_timeout 


(Input) Specifies the SSL timeout value in seconds. The timeout value controls the frequency with 
which the SSL protocol stack regenerates session keys. If ss/_timeout is set to 0, the default value 
SSLV3_CLIENT_TIMEOUT will be used. Otherwise, the value supplied will be used, provided it is 
less than or equal to 86,400. If ss/_timeout is greater than 86,400, LDAP_PARAM_ERROR is 
returned. 


pSSLReasonCode 


(Input) Specifies a pointer to the SSL Reason Code, which provides additional information in the event 
that an error occurs during initialization of the SSL stack (when Idap_ssl_client_init() is called). See 
QSYSINC/H.LDAPSSL for reason codes that can be returned. 


Example 


The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions 
are "protected" by using a secure SSL connection, including the dn and password that flow on the 
Idap_simple_bindQ: 


re = ldap_ssl_client_init (keyfile, keyfile_pw, timeout, &sslrc); 
ld = ldap_ssl_init(ldaphost, ldapport, label ); 

re = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers) ; 

re = ldap_simple_bind_s(ld, binddn, passwd); 


...additional LDAP API calls 


re = ldap_unbind( ld ); 


The following scenario depicts using the SASL EXTERNAL mechanism for authenticating the client to the 
server using the credentials in the SSL certificate: 


re = ldap_ssl_client_init (keyfile, keyfile_pw, timeout, &sslrc); 
ldap_ssl_init(ldaphost, ldapport, label ); 

ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers) ; 

re = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_ EXTERNAL, NULL, NULL, NULL 


KR 
a2 
I 


...additional LDAP API calls 


re = ldap_unbind( ld ); 


Note that the sequence of calls for the deprecated APIs is Idap_open/init(), Idap_ssl_start(), followed by 
Idap_bind(). 


The following ciphers are attempted for the SSL handshake by default, in the order shown. 


(Export Version) 


RC4_MD5_EXPORT 
RC2_MD5_EXPORT 


(Non-export Version) 


RC4_SHA_US 
RC4_MD5_US 
DES_SHA_US 
3DES_SHA_US 
RC4_MD5_EXPORT 
RC2_MD5_EXPORT 


See Idap_get/set_option() for more information on setting the ciphers to be used. 


The Idap_ssl_client_init() API includes RSA software. RSA is a trademark of RSA Data Security, Inc. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


If Idap_ssl_client_init( is not successful, it returns an LDAP error code. See LDAP Client API Error 
Conditions for possible values for the error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_ss]_client_init API. 


Related Information 


e idap_app_ssl_client_init_npQ -- Initialize the LDAP Client for a secure connection using DCM. 
e Idap_ssl_initO -- Initializes an SSL connection. 


e idap_ssl_startQ -- Creates a secure SSL connection (deprecated). 
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Idap_ssl_init --Initializes an SSL Connection. 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


LDAP *ldap_ssl_init ( 
char *host, 
int port, 
char *name) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_ssl_init() routine is used to initialize a secure SSL session with a server. The server is not actually contacted until an 
operation is performed that requires it, allowing various options to be set after initialization. Once the secure connection is established 
for the /d, all subsequent LDAP messages that flow over the secure connection are encrypted, including the ldap_simple_bindQ 


parameters, until ldap_unbind() is called. 


Although still supported, the use of the Idap_ssl_start() API is now deprecated. The Idap_ssl_client_init() and Idap_ssl_init() or 
ldap_app_ssl_client_init_npQ and Idap_app_ssl_init_np(Q) APIs should be used instead. 


Authorities and Locks 


Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated directories. 


Parameters 


host 
(Input) Several methods are supported for specifying one or more target LDAP servers, including the following: 


Explicit Specifies the name of the host on which the LDAP server is running. The host parameter may contain a 
Host List _ blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If 
present, the :port overrides the port parameter. The following are typical examples: 


ld=ldap_ssl_init ("serverl", ldaps_port, cert_label); 

ld=ldap_ssl_init ("server2:1200", ldaps_port, cert_label); 

ld=ldap_ssl_init ("serverl:800 server2:2000 server3", ldaps_port, 
cert_label); 


Localhost If the host parameter is null, the LDAP server will be assumed to be running on the local host. 


Default If the host parameter is set to "Idaps://" the LDAP library will attempt to locate one or more default LDAP 
Hosts servers, with SSL ports, using the SecureWay lIdap_server_locate() function. The port specified on the call is 


ignored, since ldap_server_locate() returns the port. For example, the following two are equivalent: 


ld=ldap_ssl_init ("ldaps://", ldaps_port, cert_label); 
ld=ldap_ssl_init (LDAPS_URL_PREFIX, LDAPS_PORT, cert_label); 


If more than one default server is located, the list is processed in sequence, until an active server is found. 


port 


name 


The LDAP URL can include a Distinguished Name, used as a filter for selecting candidate LDAP servers 
based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact match with a 
server's suffix (after normalizing for case), the server is added to the list of candidate servers. For example, the 
following will only return default LDAP servers that have a suffix that supports the specified DN: 


ld=ldap_ssl_init ("ldaps:///cn=fred, dc=austin, dc=ibm, dc=com", 
LDAPS_PORT, cert_label); 


In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one default 
server is located, the list is processed in sequence, until an active server is found. 


If the LDAP URL contains a host name and optional port, the host is used to create the connection. No attempt 
is made to locate the default server(s), and the DN, if present, is ignored. For example, the following two are 
equivalent: 


ld=ldap_ssl_init ("ldaps://myserver", LDAPS_PORT, cert_label); 
ld=ldap_ssl_init ("myserver", LDAPS_ PORT, cert_label); 


Local If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX socket (that 
Socket is, socket family is AF_UNIX) and port is ignored. This will fail for Idap_ssl_init() because UNIX sockets do 
not support SSL, nor is it necessary since data will not be flowing over the network. 


Host with Ifa specified host is prefixed with "privport://", then the LDAP library will use the rresvport() function to 

Privileged attempt to obtain one of the reserved ports (512 through 1023), instead of an "ephemeral" port. The search for 

Port a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call will fail. 
For example: 


ld=ldap_ssl_init ("privport://serverl, ldaps_port, cert_label"); 

ld=ldap_ssl_init ("privport://server2:1200", ldaps_port, cert_label); 

ld=ldap_ssl_init ("privport://server1:800 server2:2000 
privport://server3", ldaps_port, cert_label); 


(Input) The port number to which to connect. If the default IANA-assigned SSL port of 636 is desired, LDAPS_PORT should 
be specified. 


(Input) The name, or label, associated with the client private key/certificate pair in the key database. It is used to uniquely 
identify a private key/certificate pair, as stored in the key database, and may be something like: Digital ID for Fred Smith. 


If the LDAP server is configured to perform Server Authentication, a client certificate is not required (and name can be set to 
null). If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. name can 
be set to null if a default certificate/private key pair has been designated as the default (using Using Ikmgui). Similarly, name 
can be set to null if there is a single certificate/private key pair in the designated key database. 


Example 


The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions are "protected" by using 
a secure SSL connection, including the dn and password that flow on the Idap_simple_bind(): 


re 
ld 
re 
re 


ldap_ssl_client_init (keyfile, keyfile_pw, timeout, reasoncode) ; 
ldap_ssl_init(ldaphost, ldapport, label ); 

ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers) ; 
ldap_simple_bind_s(ld, binddn, passwd) ; 


-additional LDAP API calls 


re 


= ldap_unbind( ld ); 


The sequence of calls for the deprecated APIs is lIdap_open/init(), Idap_ssl_start(), followed by Idap_bind(). 


See Idap_get or set_option() for more information on setting the ciphers to be used. 


Return Value 


Session Handle 


if the request was successful. If successful, the Session Handle returned by Idap_ssl_init() is a pointer to an opaque data type 
representing an LDAP session. The Idap_get_option() and Idap_set_option() APIs are used to access and set a variety of 
session-wide parameters. See ldap_get_option() and ldap_set_option( for more information. 


NULL 


if the request was not successful. 


Error Conditions 


Idap_ssl_init() will return NULL if not successful. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_ssl_init API. 


Related Information 


e Idap_init() -- Perform an LDAP initialization operation. 
e Idap_ssl_client_init() -- Initializes the SSL library. 


e ldap_app_ssl_init_npQ -- Initializes an SSL Connection. 
e ldap_ssl_startQ) -- Creates a secure SSL connection (deprecated). 


API introduced: V4R5 


Top | Directory Services APIs | APIs by category 


Idap_ssl_start()--Start a Secure LDAP 
Connection 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


int ldap_ssl_start ( 
LDAP *ld, 
char *keyring, 
char *keyring_pw, 
char *name ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_ssl_start() function is used to start a secure connection (using Secure Sockets Layer (SSL)) to an 
LDAP server. Idap_ssl_start() accepts the /d from an ldap_open() and performs an SSL handshake to a 


server. Idap_ssl_start() must be called after Idap_open() and prior to Idap_bind(). Once the secure 
connection is established for the /d, all subsequent LDAP messages that flow over the secure connection are 
encrypted, including the Idap_bind() parameters, until lIdap_unbind() is called. 


Although still supported, the use of the Idap_ssl_start() API is now deprecated. The Idap_ssl_client_initQ) 
and Idap_ssl_initQ or ldap_app_ssl_client_init_npQ and ldap_app_ssl_init() APIs should be used instead. 


Authorities and Locks 


Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated 
directories. 


Parameters 


Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or 
Idap_open(). 

keyring 


(Input) Specifies the name of a key database file (with "kdb" extension). The key database file 
typically contains one or more certificates of certification authorities (CAs) that are trusted by the 
client. These types of X.509 certificates are also known as trusted roots. A key database can also be 
used to store the client's private key(s) and associated client certificate(s). A private key and 


associated client certificate are required only if the LDAP server is configured to require client and 
server authentication. If the LDAP server is configured to provide only server authentication, a 
private key and client certificate are not required. 


Note: Although still supported, use of the Idap_ssl_start() is discouraged (its use has been 
deprecated). Any application using the Idap_ssl_start() API should only use a single key database 
(per application process). 


A fully-qualified path and filename is recommended. If a filename without a fully-qualified path is 
specified, the LDAP library will look in the current directory for the file. The key database file 
specified here must have been created using Digital Certificate Manager, DCM. If a key database is 
not supplied, the default roots are used for trusted Certification Authorities (CAs). 


keyring_pw 


name 


(Input) Specifies the password that is used to protect the contents of the key database. This 
password is important since it protects the private key stored in the key database. The password 
was specified when the key database was initially created. A NULL pointer is accepted. 


(Input) Specifies the name, or label, associated with the client private key/certificate pair in the key 
database. It is used to uniquely identify a private key/certificate pair, as stored in the key database. 


If the LDAP server is configured to perform Server Authentication, a client certificate is not 
required (and name can be set to null). If the LDAP server is configured to perform Client and 
Server Authentication, a client certificate is required. name can be set to null if a default 
certificate/private key pair has been designated as the default (using Using DCM). Similarly, name 
can be set to null if there is a single certificate/private key pair in the designated key database. 


Return Value 


Skit error code 


-1 


if the request was successful. 


if Id is not set (NULL). 


Error Conditions 


If Id is not NULL, Idap_ssl_start() returns Skit error code, otherwise it returns -1. See gskssl.h for possible 
values of skit error codes. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_ssl_start API. 


Related Information 


e ldap _ssl_init() -- Initializes an SSL connection. 


e idap_ssl_client_initQ -- Initializes the SSL library. 


The Idap_ssl_start() API includes RSA software. RSA is a trademark of RSA Data Security, Inc. 


API introduced: V4R3 
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Idap_unbind()--Perform an LDAP Unbind 
Request 


Syntax 


#include <ldap.h> 


int ldap_unbind ( 
LDAP *ld ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_unbind() function is used to end the connection to the LDAP server and free the resources 
contained in the /d structure. 


Once it is called, any open connection to the LDAP server is closed, and the /d structure is invalid. The 
ldap_unbind_sQ and Idap_unbind() APIs are both synchronous, and can be used interchangeably. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or 
Idap_open(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


LDAP error 


if the request was not successful. 


Error Conditions 


If Idap_unbind() is not successful, it returns an LDAP error code other than LDAP_SUCCESS. See LDAP 
Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_unbind API. 


Related Information 


e idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e Idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 


e Idap_unbind_ext(Q) -- Perform an LDAP Unbind Request 
e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


e idap_set_rebind_proc() -- Sets the entry-point of a routine during the chasing of referrals. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_unbind_ext()--Perform an LDAP Unbind 
Request 


Syntax 


#include <ldap.h> 


int ldap_unbind_ext ( 
LDAP * 1d; 
LDAPControl **servctrls, 
LDAPControl **clientctrils ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_unbind_ext() function is used to end the connection to the LDAP server and free the resources 
contained in the /d structure. 


Once it is called, any open connection associated with the LDAP session handle, /d, to the LDAP server is 
closed, and any resources associated with the handle are disposed of before returning. The /d structure is 
invalid and cannot be used for any further api calls. The Idap_unbind_ext() is synchronous and allows 
server and client controls to be included. Note that since there is no server response to an unbind there is no 
way to receive a response to a server control sent with an Idap_unbind_ext(). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

serverctrls 
(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See LDAP 
Controls for more information about server controls. 

clientctrls 


(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See LDAP 
Controls for more information about client controls. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


LDAP error 


if the request was not successful. 


Error Conditions 


If ldap_unbind_ext() is not successful, it returns an LDAP error code other than LDAP_SUCCESS. See 
LDAP Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_unbind_ext API. 


Related Information 


e idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 


e Idap_unbind_sQ -- Synchronously unbind from the LDAP server and close the connection. 


API introduced: V5R1 
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Idap_unbind_s()--Perform an LDAP Unbind 
Request (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_unbind_s ( 
LDAP * 1d) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_unbind_s() function is used to end the connection to the LDAP server and free the resources 
contained in the /d structure. 


Once it is called, any open connection to the LDAP server is closed, and the /d structure is invalid. The 
Idap_unbind_s() and ldap_unbind() APIs are both synchronous and can be used interchangeably. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


Id 


(Input) Specifies the LDAP pointer returned by a previous call to Idap_initQ), Idap_ssl_initQ, or 
Idap_open(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


If ldap_unbind_s() is not successful, it returns another LDAP error code. See LDAP Client API Error 
Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_unbind_s API. 


Related Information 


e Idap_bindQ -- Asynchronously bind to the directory (deprecated). 
e Idap_bind_sQ -- Synchronously bind to the directory (deprecated). 
e Idap_sasl_bindQ -- Asynchronously bind to the directory using SASL. 


e Idap_sasl_bind_sQ -- Synchronously bind to the directory using SASL. 


e idap_simple_bindQ -- Asynchronously bind to the directory using simple authentication. 


e idap_simple_bind_sQ -- Synchronously bind to the directory using simple authentication. 


e Idap_unbindQ -- Asynchronously unbind from the LDAP server and close the connection. 


API introduced: V4R3 
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Idap_url_ parse()--Parse an LDAP URL 


Syntax 


#include <ldap.h> 


typedef struct ldap_url_desc { 
char *lud_host; LDAP host to contact */ 
int lud_port; port on host */ 
char *lud_dn; base for search */ 
char **]lud_attrs; NULL-terminate list of attributes */ 
int lud_scope; a valid LDAP_SCOPE_... value */ 
char *lud_filter; LDAP search filter */ 
char *lud_string; for internal use only */ 
} LDAPURLDesc; 


int ldap_url_parse ( 
char *url, 
LDAPURLDesc **ludpp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_url_parse() function breaks down the LDAP URL passed in url into its component pieces. The 
URLs passed in to Idap_url_parse() must be in the local codepage. Use Idap_url_parse_utf8Q for UTF-8 


URLs. 


The LDAPURLDesc structure returned by this API should be freed with ldap_free_urldesc(Q). 


This routine supports the use of LDAP URLs (Uniform Resource Locators). Supported LDAP URLs look 
like this, where sections in brackets are optional: 


ldap[s]://[hostport] [/[dn[?[attributes] [?[ scope] [?[filter]]]]]] 


where: 
e hostport is a host name with an optional ":portnumber" 
e dn is the base DN to be used for an LDAP search operation 
e attributes is a comma separated list of attributes to be retrieved 
@ scope is one of these three strings: base one sub (default=base) 


e filter is LDAP search filter as used in a call to Idap_search 


For example: 


ldap: //example.ibm.com/c=US?o0,description?one?0=ibm 


URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form 


URL: Idapurl. 


For example: 


URL: ldaps://example.ibm.com/c=US?0, description?one?o=ibm 
This form also is allowed: <URL:-ldapurl> 


For example: 


<URL: ldap://example.ibm.com/c=US?o0, description?one?o0=ibm> 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


url 
(Input) Specifies a pointer to the URL string. 
ludpp 


(Output) This result parameter will be set to a LDAPURLDesc structure containing the parsed 
URL. 


Return Value 


LDAP_SUCCESS 
If successful, an LDAP URL description is allocated, filled in, and ludpp is set to point to it. 


other LDAP Error code 


If an error occurs, one of these values is returned: 


LDAP_URL_ERR_NOTLDAP URL doesn't begin with "Idap://" 
LDAP_URL_ERR_BADSCOPE URL scope string is invalid 
LDAP_URL_ERR_ MEM can't allocate memory space 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of ldap_url_parse API. 


Related Information 


e Idap_free_urldesc() -- Frees an LDAP URL description. 
Idap_is_ldap_urlQ -- Check a URL string to see if it is an LDAP URL. 
e idap_url_parse_utf8Q -- Parse a UTF8 codepage LDAP URL string 


e Idap_url_searchQ -- Asynchronously search using an LDAP URL. 


e Idap_url_search_sQ -- Synchronously search using an LDAP URL. 


e Idap_url_search_st() -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Idap_url_parse_utf8()--Parse a UTF8 codepage 
LDAP URL string 


Syntax 


#include <ldap.h> 


typedef struct ldap_url_desc { 
char *lud_host; /* LDAP host to contact */ 
int lud_port; /* port on host */ 
char *lud_dn; /* base for search */ 
char **l]ud_attrs; /* NULL-terminate list of attributes */ 
int lud_scope; /* a valid LDAP_SCOPE_... value */ 
char *lud_filter; /* LDAP search filter */ 
char *lud_string; /* for internal use only */ 
} LDAPURLDesc; 


int ldap_url_parse_utf8 ( 
char *url, 
LDAPURLDesc **ludpp) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_url_parse_utf8() function breaks down the UTF8 codepage LDAP URL string passed in url into 
its component pieces. To parse URLs in the local codepage, use ldap_url_parse(Q. 


The LDAPURLDesc structure returned by this API should be freed with ldap_free_urldesc(Q). 


This routine supports the use of LDAP URLs (Uniform Resource Locators). Supported LDAP URLs look 
like this, where sections in brackets are optional: 


ldap[s]://[hostport] [/[dn[?[attributes] [?[ scope] [?[filter]]]]]] 


where: 
e hostport is a host name with an optional ":portnumber" 
e dn is the base DN to be used for an LDAP search operation 
e attributes is a comma separated list of attributes to be retrieved 
@ scope is one of these three strings: base one sub (default=base) 


e filter is LDAP search filter as used in a call to Idap_search 


For example: 


ldap://example.ibm.com/c=US?o0, description?one?0=ibm 


URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form 
URL: Idapurl. 


For example: 


URL: ldap: //example.ibm.com/c=US?o0, description?one?o0=ibm 
This form also is allowed: <URL-:ldapurl>. 


For example: 


<URL: ldap://example.ibm.com/c=US?o0, description?one?o0=ibm> 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


url 
(Input) A pointer to the UTF8 codepage URL string. 
ludpp 


(Output) This result parameter will be set to a LDAPURLDesc structure containing the parsed 
URL. 


Return Value 


LDAP_SUCCESS 
If successful, an LDAP URL description is allocated, filled in, and ludpp is set to point to it. 


other LDAP Error code 


If an error occurs, one of these values is returned: 


LDAP_URL_ERR_NOTLDAP URL doesn't begin with "Idap://" 
LDAP_URL_ERR_BADSCOPE URL scope string is invalid 
LDAP_URL_ERR_ MEM can't allocate memory space 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_url_parse_utf8 API. 


Related Information 


e idap_url_parse() -- Parse an LDAP URL. 
e Idap_free_urldesc() -- Frees an LDAP URL description. 
e Idap_is_Idap_urlQ -- Check a URL string to see if it is an LDAP URL. 


e Idap_url_search( -- Asynchronously search using an LDAP URL. 


e idap_url_search_sQ -- Synchronously search using an LDAP URL. 


e Idap_url_search_st() -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V5R1 
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Idap_url_search()--Perform an LDAP URL 
Search Operation 


Syntax 


#include <ldap.h> 


int ldap_url_search ( 
LDAP *ld, 
char ‘*url, 
int attrsonly) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_url_search() function is used to perform an asynchronous LDAP search based on the contents of 
the url parameter. 


This function acts like Idap_search(Q) except that the search parameters are specified by the URL. 


This routine supports the use of LDAP URLs (Uniform Resource Locators). 


LDAP URLs look like this: 


ldap[s]://[hostport] [/[dn[?[attributes] [?[ scope] [?[filter]]]]]] 


where: 
e hostport is a host name with an optional ":portnumber" 
e dn is the base DN to be used for an LDAP search operation 
e attributes is a comma separated list of attributes to be retrieved 
@ scope is one of these three strings: base one sub (default=base) 


e filter is LDAP search filter as used in a call to Idap_search 


For example: 


ldap://example.ibm.com/c=US?o0, description?one?0=ibm 


URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form 
URL: Idapurl. 


For example: 


URL: ldap: //example.ibm.com/c=US?o0, description?one?o0=ibm 


This form also is allowed: <URL:Idapurl>. 


For example: 


<URL: ldap://example.ibm.com/c=US?o0, description?one?0=ibm> 


Notes: 


1. For search operations, if hostport is omitted, host and port for the current connection are used. If 
hostport is specified, and is different from the host and port combination used for the current 
connection, the search is directed to that host and port, instead of using the current connection. In 
this case, the underlying referral mechanism is used to bind to hostport. 


2. If the LDAP URL does not contain a search filter, the filter defaults to "(objectClass=*)". 


Return Value 


Message ID of the Operation Initiated 
if the request was successful. A subsequent call to ldap_result(), can be used to obtain the result. 


-l 


if the request was not successful. 


Error Conditions 


If ldap_url_search() is not successful, -1 will be returned setting the session error parameters (/d_error) in 
the LDAP structure appropriately, which can be obtained by using Idap_get_Iderrno(). See LDAP Client 
API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_url_search API. 


Related Information 


e Idap_free_urldesc() -- Frees an LDAP URL description. 


e idap_is_Idap_urlQ -- Check a URL string to see if it is an LDAP URL. 
e idap_url_parseQ -- Break up an LDAP URL string into its components. 


e idap_url_search_sQ -- Synchronously search using an LDAP URL. 


e Idap_url_search_st() -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V4R3 
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Idap_url_ search_s() -- Perform an LDAP URL 
Search Operation (Synchronous) 


Syntax 


#include <ldap.h> 


int ldap_url_search_s ( 
LDAP *ld, 
char i BB a ee 
int attrsonly, 
LDAPMessage **res) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_url_search_s() function is used to perform a synchronous LDAP search based on the contents of 
urlparameter. 


This function acts like Idap_search_s() except that the search parameters are specified by the URL. 
This routine support the use of LDAP URLs (Uniform Resource Locators). 


LDAP URLs look like this: 


ldap[s]://[hostport] [/[dn[?[attributes] [?[ scope] [?[filter]]]]]] 


hostport is a host name with an optional ":portnumber" 


dn is the base DN to be used for an LDAP search operation 


® 

® 

e attributes is a comma separated list of attributes to be retrieved 
@ scope is one of these three strings: base one sub (default=base) 
® 


filter is LDAP search filter as used in a call to Idap_search 


For example: 


ldap://example.ibm.com/c=US?o0, description?one?0=ibm 


URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form 
URL: Idapurl. 


For example: 


URL: ldap: //example.ibm.com/c=US?o0, description?one?o=ibm 


This form also is allowed: <URL:Idapurl>. 


For example: 


<URL: ldap://example.ibm.com/c=US?o0, description?one?0=ibm> 


Notes: 


1. For search operations, if hostport is omitted, host and port for the current connection are used. If 
hostport is specified, and is different from the host and port combination used for the current 
connection, the search is directed to that host and port, instead of using the current connection. In 
this case, the underlying referral mechanism is used to bind to hostport. 


2. If the LDAP URL does not contain a search filter, the filter defaults to "(objectClass=*)". 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(). 

url 
(Input) Specifies a pointer to the URL string. 

attrsonly 
(Input) Specifies attribute information. Set to 1 to request attribute types only. Set to 0 to request 
both attribute types and attribute values. 

res 


(Output) Contains the result of the synchronous search operation. This result should be passed to 
the LDAP parsing routines (see Idap_first_entryQ, ldap_next_entry(Q), and so on). The caller is 


responsible for freeing res with ldap_msgfree(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


If Idap_url_search_s() is not successful, it returns an LDAP error code other than LDAP_SUCCESS. See 
LDAP Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of ldap_url_search_s API. 


Related Information 


e Idap_free_urldesc() -- Frees an LDAP URL description. 


e ldap_url_parse() -- Extract information from results. 


e Idap_is_Idap_urlQ -- Check a URL string to see if it is an LDAP URL. 


e idap_url_searchQ -- Asynchronously search using an LDAP URL. 
e Idap_url_search_stQ -- Synchronously search using an LDAP URL and a timeout. 


API introduced: V4R3 
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Idap_url_ search_st()--Perform an LDAP URL 
Search Operation (Timed Synchronous) 


Syntax 


#include <sys/time.h> 
#include <ldap.h> 


int ldap_url_search_st ( 
LDAP *ld, 
char *url, 
int attrsonly, 
struct timeval *timeout, 
LDAPMessage **res ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_url_search_st() function is used to perform a synchronous LDAP search with a specified timeout 
based on the contents of the url parameter. 


This function acts like Idap_search_st() except that the search parameters are retrieved from the URL. 


This routine supports the use of LDAP URLs (Uniform Resource Locators). 


LDAP URLs look like this: 


ldap[s]://[hostport] [/[dn[?[attributes] [?[ scope] [?[filter]]]]]] 


where: 
e hostport is a host name with an optional ":portnumber" 
e dn is the base DN to be used for an LDAP search operation 
e attributes is a comma separated list of attributes to be retrieved 
@ scope is one of these three strings: base one sub (default=base) 


e filter is LDAP search filter as used in a call to Idap_search 


For example: 


ldap://example.ibm.com/c=US?o0, description?one?0=ibm 


URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form 
URL: Idapurl. 


For example: 


URL: ldap: //example.ibm.com/c=US?o0, description?one?o0=ibm 
This form also is allowed: <URL:Idapurl>. 


For example: 


<URL: ldap://example.ibm.com/c=US?o0, description?one?0=ibm> 


Notes: 


1. For search operations, if hostport is omitted, host and port for the current connection are used. If 
hostport is specified, and is different from the host and port combination used for the current 
connection, the search is directed to that host and port, instead of using the current connection. In 
this case, the underlying referral mechanism is used to bind to hostport. 


2. If the LDAP URL does not contain a search filter, the filter defaults to "(objectClass=*)". 


Authorities and Locks 


No OS/400 authority is required. All authority checking is done by the LDAP server. 


Parameters 

Id 
(Input) Specifies the LDAP pointer returned by a previous call to Idap_init(), Idap_ssl_initQ, or 
Idap_open(Q). 

url 
(Input) Specifies a pointer to the URL string. 

attrsonly 
(Input) Specifies attribute information. Set to 1 to request attribute types only. Set to 0 to request 
both attribute types and attribute values. 

timeout 
(Input) Specifies a timeout value for a synchronous search issued by the Idap_url_search_st() 
routine. 

res 


(Output) Contains the result of the synchronous search operation. This result should be passed to 


the LDAP parsing routines (see ldap_first_entryQ, ldap_next_entry(Q), and so on). The caller is 
responsible for freeing res with Idap_msgfree(). 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error 


if the request was not successful. 


Error Conditions 


If Idap_url_search_st() is not successful, it returns an LDAP error code other than LDAP_SUCCESS. See 
LDAP Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_url_search_st API. 


Related Information 


e Idap_free_urldesc() -- Frees an LDAP URL description. 
e idap_url_parse(Q -- Extract information from results. 
e Idap_is_ldap_urlQ -- Check a URL string to see if it is an LDAP URL. 


e idap_url_search( -- Asynchronously search using an LDAP URL. 


e idap_url_search_sQ) -- Synchronously search using an LDAP URL. 
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Idap_value_free()--Free Memory Allocated by 
Idap_get_values() 


Syntax 


#include <ldap.h> 


void ldap_value_free ( 
char **vals) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_value_free() function frees the memory allocated by the ldap_get_values() function. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


vals 


(Input) Specifies a pointer to a null-terminated array of attribute values, as returned by 
Idap_get_values(). 


Return Value 


None 


Error Conditions 


Idap_value_free() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_value_free API. 


Related Information 


Idap_get_valuesQ -- Return an attribute's values. 


e Idap_get_values_lenQ -- Return an attribute's binary values. 


e |dap_count_values() -- Return number of values. 


e Idap_count_values_lenQ -- Return number of binary values. 


e |dap_value_free_lenQ -- Free memory allocated by Idap_get_values_len(). 
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Idap_value_free_len()--Free Memory Allocated 
by Idap_get_values_len() 


Syntax 


#include <ldap.h> 


struct berval { 
unsigned long bv_len; 
char *bv_val; 

}i 


void ldap_value_free_len ( 
struct berval *xvals) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_value_free_len() function frees the memory allocated by the ldap_get_values_len() function. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


bvals 


(Input) Specifies a pointer to a null-terminated array of pointers to berval structures, as returned by 
Idap_get_values_lenQ. 


Return Value 


None 


Error Conditions 


Idap_value_free_len() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_value_free_len API. 


Related Information 


Idap_get_valuesQ) -- Return an attribute's values. 


Idap_get_values_lenQ -- Return an attribute's binary values. 


e idap_count_values() -- Return number of values. 


e idap_count_values_lenQ -- Return number of binary values. 


e ldap_value_free() -- Free memory allocated by Idap_get_values(). 
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Idap_version -- Obtain LDAP Version and SSL 
Cipher Information 


Syntax 


#include <ldap.h> 
#include <ldapssl.h> 


int ldap_version ( 
LDAPVersion *version ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_version() routine is used to return the toolkit version (multiplied by 100). It also sets information 
in the LDAPVersion structure. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


version 


(Input) Specifies the address of an LDAPVersion structure that contains the following returned 
values: 


sdk_version Toolkit version, multiplied by 100. 
protocol_version Highest LDAP protocol supported, multiplied by 100. 
SSL_version SSL version supported, multiplied by 100. 


security_level Level of encryption supported, in bits. Set to LDAP_SECURITY_NONE if 
SSL not enabled. 


ssl_max_cipher _ A string containing the default ordered set of ciphers supported by this 
installation. See LDAP_OPT_SSL_CIPHER in Idap_set_option() for more 
information about changing the set of ciphers used to negotiate the secure 
connection with the server. 


sdk_vendor A pointer to a static string that identifies the supplier of the LDAP library. 
This string should not be freed by the application. 


sdk_build_level A pointer to a static string that identifies the build level, including the date 
when the library was built. This string should not be freed by the application. 


Return Value 


Software Developer Toolkit Version 
Sets information in the LDAPVersion structure and return the SDK VERSION. 


Error Conditions 


The Idap_version() API does not return an error code. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_version API. 
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Idap_xlate_local_to_unicode()-- Convert String 
From the Local Code Page to UCS-2 (or 
UNICODE) Encoding 


Syntax 


#include <ldap.h> 


int Ildap_xlate_local_to_unicode ( 
char *inbufp, 
unsigned long *inlenp, 
char *outbufp, 
unsigned long *outlenp ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_xlate_local_to_unicode() API is used to convert a string from the local code page to the UCS-2 
encoding as defined by ISO/IEC 10646-1. This same set of characters is also defined in the UNICODE 
standard. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


inbufp 
(Input) A pointer to the address of the input buffer containing the data to be translated. 
inlenp 


(Input) Length in bytes of the inbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of in/enp buffer that is left to be translated. 


outbufp 
(Output) A pointer to the address of the output buffer for translated data. 
outlenp 


(Output) Length in bytes of the outbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of outlenp buffer space left available for translated 
data. 


Note that in general, the output buffer should be three times as large as the input buffer if the intent 


is to translate the entire input buffer in a single call. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_xlate_local_to_unicode() API will return an LDAP error code other than LDAP_SUCCESS if 
not successful. See LDAP Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 


CPF3CF2 E Error(s) occurred during running of ldap_xlate_local_to_unicode API. 


Related Information 


e idap_xlate_utf8_to_local(Q -- Convert string from UTF-8 to local code page. 
e Idap_xlate_local_to_utf8Q -- Convert string from local to UTF-8 code page. 


e Idap_xlate_unicode_to_local() -- Convert string from UCS-2 to local code page. 


e Idap_get_iconv_local_codepage() -- Get the active LDAP code page. 


e Idap_set_iconv_local_codepage() -- Set the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


e Idap_set_locale( -- Change the locale used by LDAP. 
e Idap_get_localeQ -- Get the locale used by LDAP. 
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Idap_xlate_local_to_utf8()-- Convert String 
From the Local Code Page to UTF-8 Encoding 


Syntax 


#include <ldap.h> 


int Ildap_xlate_local_to_utf8 ( 
char *inbufp, 
unsigned long *inlenp, 
char *outbufp, 
unsigned long *outlenp ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_xlate_local_to_utf8() API is used to convert a string from the local code page to a UTF-8 
encoding (which is used by LDAP when communicating with an LDAP V3 compliant server). 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


inbufp 
(Input) A pointer to the address of the input buffer containing the data to be translated. 
inlenp 


(Input) Length in bytes of the inbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of in/enp buffer that is left to be translated. 


outbufp 
(Output) A pointer to the address of the output buffer for translated data. 
outlenp 


(Output) Length in bytes of the outbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of outlenp buffer space left available for translatd 
data. 


Note that in general, the output buffer should be three times as large as the input buffer if the intent 
is to translate the entire input buffer in a single call. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_xlate_local_to_utf8Q will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_xlate_local_to_utf8 API. 


Related Information 


e idap_xlate_utf8_to_local(Q -- Convert string from UTF-8 to local code page. 


e idap_xlate_local_to_unicode() -- Convert string from the local to UCS-2 code page. 


e Idap_xlate_unicode_to_local() -- Convert string from UCS-2 to local code page. 


e idap_get_iconv_local_codepage() -- Get the active LDAP code page. 
e Idap_set_iconv_local_codepage() -- Set the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


Idap_set_localeQ) -- Change the locale used by LDAP. 


e Idap_get_localeQ -- Get the locale used by LDAP. 
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Idap_xlate_unicode_to_local() -- Convert String 
From the UCS-2 (or UNICODE) Encoding to 
Local Code Page 


Syntax 


#include <ldap.h> 


int ldap_xlate_unicode_to_local ( 
char *inbufp, 
unsigned long *inlenp, 
char *outbufp, 
unsigned long *outlenp ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_xlate_unicode_to_local() API is used to convert a UCS-2 encoded string to the local code page 
encoding. 


It is important to note that translation of strings from a UCS-2 (or UNICODE) encoding to local code page 
may result in loss of data when one or more characters in the UCS-2 encoding cannot be represented in the 
local code page. When this occurs, a substitution character replaces any UCS-2 characters that cannot be 
converted to the local code page. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


inbufp 
(Input) A pointer to the address of the input buffer containing the data to be translated. 
inlenp 


(Input) Length in bytes of the inbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of in/enp buffer that is left to be translated. 


outbufp 
(Output) A pointer to the address of the output buffer for translated data. 
outlenp 


(Output) Length in bytes of the outbufp buffer. This value is decremented when the conversion is 


done, such that on return it indicates the length of outlenp buffer space left available for translated 
data. 


Note that in general, the output buffer should be three times as large as the input buffer if the intent 
is to translate the entire input buffer in a single call. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_xlate_unicode_to_local() API will return an LDAP error code if not successful. See LDAP 
Client API Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_xlate_unicode_to_local API. 


Related Information 


e Idap_xlate_utf8_to_local(Q -- Convert string from UTF-8 to local code page. 
e Idap_xlate_local_to_utf8Q -- Convert string from local to UTF-8 code page. 


e Idap_xlate_local_to_unicode() -- Convert string from local to UCS-2 code page. 


e Idap_get_iconv_local_codepage() -- Get the active LDAP code page. 


e Idap_set_iconv_local_codepage() -- Set the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


e Idap_set_localeQ -- Change the locale used by LDAP. 
e Idap_get_localeQ -- Get the locale used by LDAP. 
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Idap_xlate_utf8_to_local() -- Convert String 
From the UTF-8 Encoding to Local Code Page 


Syntax 


#include <ldap.h> 


int Ildap_xlate_utf8_to_local ( 
char *inbufp, 
unsigned long *inlenp, 
char *outbufp, 
unsigned long *outlenp ) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDCLNT 


Threadsafe: Yes 


The Idap_xlate_utf8_to_local() API is used to convert a UTF-8 encoded string to the local code page 
encoding. 


It is important to note that translation of strings from a UTF-8 encoding to local code page may result in 
loss of data when one or more characters in the UTF-8 encoding cannot be represented in the local code 
page. When this occurs, a substitution character replaces any UTF-8 characters that cannot be converted to 
the local code page. 


Authorities and Locks 


No OS/400 authority is required. 


Parameters 


inbufp 
(Input) A pointer to the address of the input buffer containing the data to be translated. 
inlenp 


(Input) Length in bytes of the inbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of the in/enp buffer that is left to be translated. 


outbufp 
(Output) A pointer to the address of the output buffer for translated data. 
outlenp 


(Output) Length in bytes of the outbufp buffer. This value is decremented when the conversion is 
done, such that on return it indicates the length of outlenp buffer space left available for translated 
data. 


Note that in general, the output buffer should be three times as large as the input buffer if the intent 
is to translate the entire input buffer in a single call. 


Return Value 


LDAP_SUCCESS 


if the request was successful. 


another LDAP error code 


if the request was not successful. 


Error Conditions 


The Idap_xlate_utf8_to_local() will return an LDAP error code if not successful. See LDAP Client API 
Error Conditions for possible LDAP error code values. 


Error Messages 


The following message may be sent from this function. 


Message ID Error Message Text 
CPF3CF2 E Error(s) occurred during running of Idap_xlate_utf8_to_local API. 


Related Information 


e Idap_xlate_local_to_utf8Q -- Convert string from the local to UTF-8 code page. 
e idap_xlate_local_to_unicode() -- Convert string from the local to UCS-2 code page. 


e Idap_xlate_unicode_to_local() -- Convert string from UCS-2 to local code page. 


e Idap_get_iconv_local_codepage() -- Get the active LDAP code page. 


e idap_set_iconv_local_codepage() -- Set the active LDAP code page. 


e Idap_set_iconv_local_charset() -- Set the active LDAP character set. 


Idap_set_localeQ) -- Change the locale used by LDAP. 
e Idap_get_localeQ -- Get the locale used by LDAP. 
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Configure Directory Server (QgldCfgDirSvr) 


Required Parameter Group: 


Input data Char(*) 
Length of input data Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDUAPI 


Threadsafe: No 


The Configure Directory Server (QgldCfgDirSvr) API creates the initial directory server configuration. 
This includes identifying the library that will contain the underlying database objects, the administrator of 
the server, and the initial set of suffixes to be present on the server. 


Authorities and Locks 


*ALLOBJ and *LOSYSCFG special authority is required to use this API. 


Required Parameter Group 


Input data 
INPUT; CHAR(*) 


Data that describes the desired directory server configuration. The content and format of this 
structure are determined by the format name. See Format of Input Data for a description of these 


formats. 


Length of input data 
INPUT; BINARY(4) 


The length of the input data structure. 
Format name 
INPUT; CHAR(8) 


The content and format of the input configuration data. The possible format name follows: 


CFGDO100_ Configure Directory Server. 


See Format of Input Data for a description of these formats. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Input Data 


For details about the format of the input data, see the following sections. For details about the fields in each 
format, see Field Descriptions. 


CFGD0100 Format 


This format is used to provide initial configuration data about the directory server. 


[Offset 
= c | Hex {Type Field 


| | [BINARY (4) [Offset to database path 
[ 4 | [BINARY(4) [Length of database path 


BINARY(4) Offset to administrator distinguished name 
= . ee ) 


[12 | © |BINARY@) [Length of administrator DNS 
[24 [18 |BINARYG) [Offsettosuffixes —~—~S~SC~C~S~S~S~S~*S 


Field Descriptions 


Administrator DN. The distinguished name of a directory object that has access to all objects in the 
directory. This field is specified in UCS-2 (CCSID 13488). 


Administrator password. The password used when you connect to the directory as the administrator. This 
field is specified in UCS-2 (CCSID 13488). 


Database path. The path to an existing library containing the directory database objects. This is an 
integrated file system path name, for example, /QSYS.LIB/QDIRSRV.LIB. #The library must exist in a 
system ASP or a basic user ASP (ASP value of 1 to 32). The library cannot exist in an independent ASP 
(ASP value greater than 32). *& This field is specified in UCS-2 (CCSID 13488). 


Displacement to next suffix. The displacement, in bytes, from the start of the current suffix entry to the 
next suffix entry. 


Displacement to suffix name. The displacement, in bytes, from the start of the current suffix entry to the 
suffix name field. 


Length of administrator DN. The length, in Unicode characters, of the administrator DN 


Length of administrator password. The length, in Unicode characters, of the administrator password 
field. 


Length of database path. The length, in Unicode characters, of the database path field. 
Length of suffix name. The length, in Unicode characters, of the suffix name field. 
Number of suffixes. The number of suffixes present in the suffix list. 


Offset to administrator DN. The offset, in bytes, from the start of the input data to the administrator DN 
field. 


Offset to administrator password. The offset, in bytes, from the start of the input data to the administrator 
password field. 


Offset to database path. The offset, in bytes, from the start of the input data to the database path field. 
Offset to suffixes. The offset, in bytes, from the start of the input data to the list of suffixes. 
Reserved. A reserved field. This field must be set to zero. 


Suffixes. The list of suffixes to be present on the server. At least one must be present in the initial 
configuration. 


Suffix name. The distinguished name of the root of a directory tree present on the server.This field is 
specified in UCS-2 (CCSID 13488). 


Error Messages 


Message ID Error Message Text 

CPF2209 E Library &1 not found. 
CPFAODB E Object name not a QSYS object. 
CPFA314 E Memory allocation error. 
GLD0205 E Administrator DN not valid. 
GLD020A E Suffix not valid. 


GLD021C E *ALLOBJ and *IOSYSCFG special authority required. 


GLD0223 E Database path not valid. 
GLD0228 E Validation list not created. 
GLD022A E Server configuration cannot be modified while the server is active. 


2» GLD0236 E Database library must be in system ASP or basic user ASP.*& 
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Change Directory Server Attributes 
(QgldChgDirSvrA) 


Required Parameter Group: 


Input data Char(*) 
Length of input data Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDUAPI 


Threadsafe: No 


The Change Directory Server Attributes (QgldChgDirSvrA) API changes the directory server 
configuration. It can be used to change the following server properties: 


e General server properties 
e Suffixes served by this server 


e Encrypted connection configuration. The Secure Sockets Layer (SSL) is used for encrypted 
communication. 


e Performance settings 


Authorities and Locks 


*ALLOBJ and *IOSYSCFG special authority is required to use this API with formats CSVRO100, 
CSVR0200, CSVR0300, CSVR0400, CSVR0500, CSVR0600, or 4* CSVRO800. *& *AUDIT special 
authority is required to use this API with format CSVRO700. 


Required Parameter Group 


Input data 
INPUT; CHAR(*) 


A variable that contains the input data. See Format of Input Data for a description of the data 
associated with a specific format name. 


Length of input data 
INPUT; BINARY(4) 


The length of the input data area. 


Format name 


INPUT; CHAR(8) 


The format name identifying the type of information to be changed. The possible format names 
follow: 


CSVRO100 Basic server configuration 

CSVRO200 Add or remove suffixes from this server 

CSVRO300 Add, change, or remove directory indexing rules 

CSVRO400 Add or change the attributes for publishing users in an LDAP directory. 


CSVRO500 Add or change the network server publishing attributes associated with the 
LDAP server. 


CSVRO600 Add or change referral server information 
CSVRO700 Server auditing information 


= CSVRO800 _ IP address information*® 


See Format of Input Data for a description of these formats. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Input Data 


For details about the format of the input data, see the following sections. For details about the fields in each 
format, see Field Descriptions. 


CSVR0100 Format 


This format is used to change basic server configuration information. 


| Offset 
es Hex |Type Field 


Tt passer a 
NA Si 
i BIN aR [Encrypted portmumber 
See BIN aR = 


| 32 [| 20 |BINARY()  [Maximumconnections = = 
| 36 | 24 |BINARY(4) [Reserved 
[ 40 | 28 |BINARYG) |Referalpot ~~~SOSOSC~S~S~S 
= IC De 
5a NAV — ft anno 
sa NAV xine 
| 68 [BINARY(4) {Length of administrator password 
5 BINARY oat soes DN 
| 76 [| 4C |BINARY(4)  [LengthofupdaeDN == 
EEE DO ae 
ae | a iNav [Offsettokeyringfile = 
[92 | SC |BINARYG) [Length ofkeyringfile —~—=~S~S~S~S~*S 
| 96 | 60 |BINARY(4)  |Offsettodatabase path == 
| 100 [ 64 |BINARY(4) [Length ofdatabasepath = 
| 104 [ 64 |BINARY(4) |Levelindicator = = 
Additional fields if level indicator is equal to 1 or greater: 

| 108 [ 68 |BINARY(4) [SSL authentication method = 
2 Ee On i 
iat —| HE BINARY [oH maser over URE 
[ 124 [ 7c oe [Length of master server URL 
ie] RINARYGO— ose eee 
[140 | 8C |BINARY@ [Reserved ~~~~SOSOC~C~CS*~S 
[Additional fields if level indicator is equal to2 or greater; 
[| 144 [ 90 |BINARY(4) — Kerberos authentication indicator = 
| 148 | 94 |BINARY(4)  |Offsetto Kerberoskeytabfile = 
[| 152 [ 98 |BINARY(4) [Length of Kerberos keytabfile == 
| 156 [| 9C  |BINARY(4) [Kerberos to DN mapping indicator = 
[| 164 [ A4 |BINARY(4) — [Length of Kerberos administrator ID = 
| 168 [ A8 |BINARY(4) [Offset to Kerberos administrator realm = 
| 176 [| BO |BINARY(4) — [Event notification registration indicator 
22 Be Oe 
Ts |CBC BINARY MG pains er Ga 


| 192 | CO |BINARY(4) [Maximum pending transactions = 
| 196 | C4 |BINARY(4)  |Transactiontime limit = 
| 200 [ C8 |BINARY(4) [ACLmodel 
| 204 [| CC |BINARY() [Reserved 
[®*Additional fields if level indicator is equal to 3 or greater: 

| 208 | DO |BINARY(4) [Level of authority integration = 
| 216 | D8 |BINARY(4) [Offset to projected suffix, = 
[Variable length string fields: 
| | [CHAR(*) [Referral server 

| | [CHAR(*) [Update DN 

[ [| ——s [CHARG@) —[Keyringfile 
[ [ss CHARG@) Database path 
|; = | — |CHARC!) ——[MasterserverURL-s—— 
[| = [  |CHARC*) [Kerberos administratorID- 
[| = [| ~~ |CHARC*) [Kerberos administrator realm = 


CSVR0200 Format 


This format is used to add or remove suffixes from the server. The input data consists of a header and a 
series of change entries. The header identifies the number of suffixes to be added or removed. Each change 
entry identifies a suffix and the action to be performed (add or remove the suffix). 


Note: Removing a suffix from a server will result in the loss of all directory entries with that suffix. 


| Offset 
ae c | Hex |Type Field 


ie es Oe CL 
[Changeentry = ss—s—“—sS 
Suffix change entries: 


[12 | © |BINARY@) |Lengthofsuffix ~=~SCS~*~S 


CSVR0300 Format 


This format is used to add, change, or remove directory indexes. Creating indexes for one or more attributes 
allows for faster retrieval of directory entries based on those attributes. The input data consists of a header 
and a series of change entries. The header identifies the number of indexes to be added, changed, or 
removed. Each change entry identifies an attribute and the action to be performed (add, change, or remove 
the indexes). 


Starting with V4R5M6O, this format is not supported. Database index information is to be changed using an 
LDAP client or the Directory Management Tool (DMT) starting with V4R5MO. 


[Offset 
a c | Hex |Type Field 


| | [BIN ARY(4) [Offset to change entry 
| 4 | 4 [BIN ARY(4) [N umber of change entries 


Change entries 


Add or se attribute index entries: 


| | [BI NARY(4) [Displacement to next entry 


BINARY(4) Action 


| 8 [BINARY (4) [Displacement to attribute name 
C [B INARY(4) [Length of attribute name 


| 


BIN — Index type 


SHAR) — [estos as ———————— 
Delete attribute index entries: 

[| 0 [| 0 |BINARY() — [Displacementtonextentry = = == 
[ 4 [ 4  JBINARY() [Action 000 
| 8 [| 8 J|BINARY(4) — [Displacementtoattributename = 
| 12 [ C  |BINARY() Length ofattributename = 
[16 | 10 |BINARYG) [Reserved ~~~ ~SOSOSOCS~S 
[CHAR(*) —[Attributemame 


| 


ttt 


CSVR0400 Format 


This format is used to set the attributes for publishing users in an LDAP directory. User information from 
the System Distribution Directory (SDD) can be published to an LDAP server by the Synchronize System 
Distribution Directory to LDAP (QGLDSSDD) API and from iSeries Navigator. The publishing attributes 
define how to publish user information. 


| Offset 
ae c | Hex |Type Field 


| | [BIN ARY(4) [Offset to the server name 
| 4 | 4 [BIN ARY(4) [Length of server name 


[| 8 [| 8 BINARY) |LDAPportnumber = 
| 12 | C  |BINARY(@)  |Connectiontype = 
| 16 [ 10 |BINARY(4) — [Offset to parent distinguished name = 
| 20 [ 14 |BINARY() [Length of parent distinguishedname = 
[24 | 18 |BINARY@ [Reserved =~ ~~ SOSOSOSCS~S 
Variable length string fields: 

[| = [ — |CHAR(!) —[Servername 
; [| — |CHARC*) [Parent distinguished name 


CSVR0500 Format 


This format is used to set the network server publishing attributes associated with the server. 


| Offset 
| Dec | Hex |Type Field 


[| 0 | 0 |BINARY(4)  |Offsettochangeentries = === 
[| 4 [| 4  |BINARY(4) [Number ofchangeentries = = = 
| | [Change entries 

Add or change publishing agent change entries: 

[| 0 [| 0 [BINARY@) __[Pisplacementtonextenty 
ie] TO RINARYGO [tapos ssa 
[20 | 14 |BINARY@)  |Lengthofservermame—~—S~S~S~S 
| 24 [ 18 |BINARY(4)  [DisplacementtobindDN = = 
= 1c Re 
ae [ie— BINARY) — [Comesion ses 
| 48 [| 30 |BINARY(4) — [Displacement to parent distinguished name 
| 52 [| 34 |BINARY(4) — [Length of parent distinguishedname = 
| 60 [| 3C |BINARY(4) [Levelindicator = = 
Additional fields if level indicator is equal to 1 

| 64 | 40 |BINARY(4) Kerberos authentication indicator 

[68 | 44 BINARY) _[Pisplacement to Kerberos key tab Ale 
| [BINARY(4) {Length of Kerberos key tabfile = 
ae NAR) — met Kes pina ——— 


[ 16 | 10 |BINARY@) [Reserved ~~~ SCS 


CSVR0600 Format 


This format is used to change referral server configuration information. The input data consists of a header 
and a series of change entries. The header identifies the master server information and the number of 
referral servers. This replaces the referral server information, if any, that is currently configured. 


| Offset 
| Dec | Hex /Type Field 


[| 0 | 0 |BINARY(4)  |Offsettochangeentries = = == 
[| 4 [| 4  |BINARY(4) [Number ofchangeentries = = == 
| | [Change entries 

Referral server change entries: 


CSVRO0700 Format 


This format is used to change the server auditing configuration information. 


| Offset 
| Dec | Hex /Type Field 


| 0 0 BINARY(4) [Security audit option for objects 
| 4 4 BINARY(4) Reserved 


a 


CSVR0800 Format 


This format is used to change the IP address configuration information. The input data consists of a header 
and a series of change entries. The header identifies the number of IP addresses in the list. This replaces the 
IP address information that is currently configured. At least one IP address value must be specified for the 
server. 


| Offset 
see Hex |Type Field 


ee a CCE 
[4 [| 4 [BINARY |Numberof change entries —~—~CS~* 
a [Changeentry 
IP address entries: 


Field Descriptions 


ACL model. Indicator of the ACL model to use. The following special values may be specified: 
-1 The value of this field does not change. 


I Use the ACL model that supports attribute-level ACL permissions. This may cause compatibility 
problems with replication and applications that manage access-class level permissions defined in 
releases prior to VSR1MO. Once enabled, this capability can be disabled only by reconfiguring your 
server and deleting the directory database. 


Action. The action to be performed for a given entry. The following values may be specified: 
I Add suffix, index rule, or publishing agent 
2 Change index rule or publishing agent 


3 Remove suffix, index rule, or publishing agent 


Note: Change is valid only for the CSVR0300 and CSVRO500 formats. 


Administrator DN. A distinguished name that has access to all objects in the directory. When either the 
administrator DN or the administrator password field is changed, both must be specified. This field is 
specified in UCS-2 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field 
of zero. 


Administrator password. The password used when connecting to the directory server using the 
administrator DN. When either the administrator DN or the administrator password field is changed, both 
must be specified. This field is specified in UCS-2 (CCSID 13488). To leave the value unchanged, specify 
a length and offset to this field of zero. 


Attribute index entries. The list of changes to be made to the attribute indexes. 


Attribute name. The name of a directory object attribute for which database indexes will be created. This 
field is specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*DEFAULT Specifies the index types to be created for those attributes that have no explicit rules 
defined. 


Note: The *DEFAULT attribute entry may be removed or added. Adding or removing *DEFAULT 
attribute is equivalent to not creating any indexes, or creating indexes for all attributes, depending on the 
index types specified. 


Bind credentials. The password used when connecting to the directory server using the bind DN. When 
either the bind DN or the bind credentials field is changed, both must be specified. This field is specified in 
UCS-2 (CCSID 13488). To leave the value unchanged, specify a length and displacement to this field of 
Zero. 


Bind DN. A distinguished name to use when publishing objects to the directory. When either the bind DN 
or the bind credentials field is changed, both must be specified. This field is specified in UCS-2 (CCSID 
13488). To leave the value unchanged, specify a length and displacement to this field of zero. 


Change entry. A structure identifying a change to be made. The structure identifies the suffix, attribute, or 
publishing agent and the operation to be performed (add, change, or delete). 


Change log indicator. The indicator of whether to have a change log for entries that are added, changed or 
deleted. The following values may be specified: 


0 No, do not have a change log 
I Yes, have a change log 


-1 The value remains the same 


Connection type. The type of connection to use to the LDAP server. The following values may be 
specified: 


I Nonsecure 
2 Secured, using SSL 


-1 The value remains the same 


Current cipher protocols. The cipher protocols that the server will allow when using encrypted 
connections. The following values may be specified: 


-1 The value remains the same 


Or the sum of one or more of the following values: 


0x0100 Triple Data Encryption Standard (DES) Secure Hash Algorithm (SHA) (U.S.) 


0x0200 DES SHA (U.S.) 

0x0400 Rivest Cipher 4 (RC4) SHA (U.S.) 
0x0800 RC4 Message Digest 5 (MDS) (U.S.) 
0x1000 RC2 MDS (export) 

0x2000 RC4 MDS (export) 


2 0x4000 Advanced Encryption Standard (AES) SHA (U.S.) 


Database path. The path to an existing library containing the directory database objects. This is an 
integrated file system path name, for example, /QSYS.LIB/DIRSRV.LIB. By changing this field, you make 
the current directory contents inaccessible. By changing the field back to its original value, you restore the 
original directory contents. #*The library must exist in a system ASP or a basic user ASP (ASP value of 1 
to 32). The library cannot exist in an independent ASP (ASP value greater than 32). *& This field is 
specified in UCS-2 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field 
of zero. 


Disable publishing agent. Indicates whether or not the publishing agent is disabled. The following values 
may be specified: 


0 The publishing agent is enabled. 
I The publishing agent is disabled. 


Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the 
attribute name field. 


Displacement to bind credentials. The displacement, in bytes, from the start of the current entry to the 
bind credentials field. 


Displacement to bind DN. The displacement, in bytes, from the start of the current entry to the bind DN 
field. 


2Displacement to IP address. The displacement, in bytes, from the start of the current entry to the IP 
address field.“ 


Displacement to Kerberos key tab file. The displacement, in bytes, from the start of the current entry to 
the Kerberos key tab file field. 


Displacement to Kerberos principal. The displacement, in bytes, from the start of the current entry to the 
Kerberos principal field. 


Displacement to Kerberos realm. The displacement, in bytes, from the start of the current entry to the 
Kerberos realm field. 


Displacement to next entry. The displacement, in bytes, from the start of the current entry to the next 
entry in the input data. 


Displacement to parent distinguished name. The displacement, in bytes, from the start of the current 
entry to the parent distinguished name field. 


Displacement to publishing agent name. The displacement, in bytes, from the start of the current entry to 
the publishing agent name field. 


Displacement to referral server URL. The displacement, in bytes, from the start of the current entry to the 
referral server URL field. 


Displacement to server name. The displacement, in bytes, from the start of the current entry to the server 
name field. 


Displacement to suffix. The displacement, in bytes, from the start of the current entry to the suffix field. 
Encrypted port number. The port number to use for encrypted connections. The standard port number for 
encrypted connections (SSL) is 636. Valid port numbers are in the range 1 to 65535. The following special 


value may be specified: 


-1 The value of this field does not change. 


Event notification registration indicator. Indicator of whether to allow client to register for event 
notification. The following special values may be specified: 


-1 The value of this field does not change. 
O  Donotallow clients to register for event notification. 


I Allow clients to register for event notification. 


Index type. The kind of database indexes that will be created for an attribute. Creating database indexes 
improved the performance of directory searches on those attributes. The following values may be specified: 


0 No indexes will be maintained for the specified attribute 


I Equal 


Note: For a delete request, 0 must be specified for this field. 

2>IP address. The IPv4 address on which the directory server will accept connections. The IP address must 
already exist to be specified. A value of hexadecimal zeroes and leading zeroes is not allowed. An address 
is expressed in standard dotted-decimal form www.xxx.yyy.zzz; for example, 130.99.128.1. This field is 
specified in UCS-2 (CCSID 13488). 


The following special value may be specified: 


*ALL All IP addresses defined on the local system will be bound to the server.*& 


Kerberos administrator ID. The name of the Kerberos administrator. This field is specified in UCS-2 
(CCSID 13488). The following special value may be specified: 


*NONE_ No value is specified. 


To leave the value unchanged, specify a length and offset to this field of zero. 


Kerberos administrator realm. The realm where the kerberos administrator is registered. This field is 
specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


To leave the value unchanged, specify a length and offset to this field of zero. 


Kerberos authentication indicator. The following special values may be specified: 


-1 The value of this field does not change. 
0 Do not support Kerberos authentications. 


I Support Kerberos authentications. Ensure all Kerberos fields are specified. 


Kerberos key tab file. The integrated file system path name for the key tab file that contains the server's 
secret key used for authentication. The QDIRSRV user profile is given authorization to read this file. This 
field is specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


To leave the value unchanged, specify a length and offset or displacement to this field of zero. 


Kerberos principal. The principal in the key tab file to use for authentication. This field is specified in 
UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE_ No value is specified. 


To leave the value unchanged, specify a length and offset or displacement to this field of zero. 


Kerberos realm. The realm where the principal is registered to use for authentication. This field is 
specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


To leave the value unchanged, specify a length and offset or displacement to this field of zero. 
Kerberos to DN mapping indicator. 
-1 The value of this field does not change. 


O Map the Kerberos ID to pseudo DN. A pseudo DN can be used to uniquely identify an LDAP user 
object of the form 'ibm-kerberosName=principal @realm" or 'ibm-kn=principal @realm". 


I Use associated DN in directory. The LDAP server will attempt to find an entry in the directory that 


contains the kerberos principle and realm as one of its attributes. Once found, this DN will then be 
used to determine the client's authorizations to the directory. 


Key ring file. The path name of the SSL key ring file. A key ring file must be configured when using SSL. 
The following special value may be specified: 


*NONE No value is specified. 


Note: Starting with V4R4M0O, this field is ignored for format CSVRO100. This field is specified in UCS-2 
(CCSID 13488). 


To leave the value unchanged, specify a length and offset to this field of zero. 
LDAP port number. The LDAP server's TCP/IP port. The following values may be specified: 


-1 The value remains the same 


Length of administrator DN. The length, in Unicode characters, of the administrator DN field. 


Length of administrator password. The length, in Unicode characters, of the administrator password 
field. 


Length of attribute name. The length, in Unicode characters, of the the attribute name field. 
Length of bind credentials. The length, in Unicode characters, of the bind credentials field. 
Length of bind DN. The length, in Unicode characters, of the bind DN field. 

Length of database path. The length, in Unicode characters, of the database path field. 
Length of IP address. The length, in Unicode characters, of the IP address field.“ 


Length of Kerberos administrator ID. The length, in Unicode characters, of the Kerberos administrator 
ID field. 


Length of Kerberos administrator realm. The length, in Unicode characters, of the Kerberos 
administrator realm field. 


Length of Kerberos key tab file. The length, in Unicode characters, of the Kerberos key tab file field. 
Length of Kerberos principal. The length, in Unicode characters, of the Kerberos principal field. 
Length of Kerberos realm. The length, in Unicode characters, of the Kerberos realm field. 

Length of key ring file. The length, in Unicode characters, of the key ring file field. 

Length of master server URL. The length, in Unicode characters, of the master server URL field. 


Length of parent distinguished name. The length, in Unicode characters, of the parent distinguished 
name field. 


“Length of projected suffix. The length, in Unicode characters, of the projected suffix field.“ 


Length of publishing agent name. The length, in Unicode characters, of the publishing agent name. The 
length can be at most 50 Unicode characters. 


Length of referral server. The length, in Unicode characters, of the referral server name. 

Length of referral server URL. The length, in Unicode characters, of the referral server URL field. 
Length of server name. The length, in Unicode characters, of the server name field. 

Length of suffix. The length, in Unicode characters, of the the suffix field. 

Length of update DN. The length, in Unicode characters, of the update DN field. 

Length of update password. The length, in Unicode characters, of the update password field. 


Level indicator. The level indicator of the data supplied for a format. See the format descriptions for 
possible uses and values of this field. 


2Level of authority integration. The level of OS/400 authority integration to use to determine if a 
distinguished name (DN) can become an LDAP administrator. Allowing a user profile to become an LDAP 
administrator can be done by setting the 'Level of authority integration’ to 'l' and then authorizing specific 
user profiles to the ‘Directory Services Administrator’ function of the operating system through iSeries 
Navigator's Application support. The Change Function Usage Information (QS YCHFUD) API, with a 
function ID of QIBM_DIRSRV_ADMIN, can also be used to change the list of users that are allowed to be 


an LDAP administator. The user profile can be mapped to a DN as a projected user (for example, for user 
profile 'FRED’, and the projected suffix of 'systemA’, the projected user's DN would be 
os400-profile=FRED,cn=accounts,os400-sys=systemA ). 

The following special values may be specified: 


-1 The value of this field does not change. 


0 Do not apply 'Directory Services Administrator’ function identifier to bound distinguished names to 
determine LDAP administrators. 


I Allow bound distinguished names that refer directly to user profiles to become LDAP administrators 
if the user profile is identified in the 'Directory Services Administrator’ function identifier. 


Master server URL. The uniform resource locator (URL) of the master server. This field is specified in 
UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE_ No value is specified. 


To leave the value unchanged, specify a length and offset to this field of zero. 


Maximum connections. The maximum number of simultaneous connections that can be established with 
the server. The following special values may be specified: 


-1 The value of this field does not change. 


O Do not limit the number of connections. 


Note: Starting with VSR1M0O, this field is no longer supported and is ignored if a value is passed. 
Maximum event registrations for connection. The following special values may be specified: 
-1 The value of this field does not change. 


0 Do not limit the number of event registrations for connection. 


Maximum event registrations for server. The following special values may be specified: 
-1 The value of this field does not change. 


O Do not limit the number of event registrations for server. 


Maximum number of change log entries. The maximum number of change log entries that can be stored. 
If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value 
only used if 'Change log indicator’ is set to 1. The following special values may be specified: 


-1 The value of this field does not change. 


0 Do not limit the number of change log entries. 


Maximum operations per transaction. The maximum number of operations that are allowed for each 
transaction. Transaction support allows a group of directory changes to be handled as a single transaction. 
The following special values may be specified: 


-1 The value of this field does not change. 


Maximum pending transactions. The maximum number of pending transactions allowed. Transaction 
support allows a group of directory changes to be handled as a single transaction. The following special 
value may be specified: 


-1 The value of this field does not change. 


Nonencrypted port number. The port number to be used for nonencrypted connections. The standard port 
number is 389. Valid port numbers are in the range 1 to 65535. The following special value may be 
specified: 


-1 The value of this field does not change. 


Number of change entries. The number of change entries present in the input data. 


Number of database connections. The number of database connections used by the server. Valid numbers 
are in the range 4 to 32. The following special value may be specified: 


-1 The value of this field does not change. 


Offset to administrator DN. The offset, in bytes, from the start of the input data area to the administrator 
DN field. 


Offset to administrator password. The offset, in bytes, from the start of the input data area to the 
administrator password field. 


Offset to change entry. The offset, in bytes, from the start of the input data area to the the first change 
entry. 


Offset to database path. The offset, in bytes, from the start of the input data area to the database path field. 


Offset to Kerberos administrator ID. The offset, in bytes, from the start of the input data area to the 
Kerberos administrator ID field. 


Offset to Kerberos administrator realm. The offset, in bytes, from the start of the input data area to the 
Kerberos administrator realm field. 


Offset to Kerberos key tab file. The offset, in bytes, from the start of the input data area to the Kerberos 
key tab file field. 


Offset to key ring file. The offset, in bytes, from the start of the input data area to the key ring file field. 


Offset to master server URL. The offset, in bytes, from the start of the input data area to the master server 
URL field. 


Offset to parent distinguished name. The offset, in bytes, from the start of the input data area to the 
parent distinguished name field. 


Offset to projected suffix. The offset, in bytes, from the start of the input data area to the projected 
suffix field. 


Offset to referral server. The offset, in bytes, from the start of the input data area to the referral server 
field. 


Offset to server name. The offset, in bytes, from the start of the input data to the server name field. 


Offset to suffix. The offset, in bytes, from the start of the input data area to the suffix field. 


Offset to update DN. The offset, in bytes, from the start of the input data area to the update DN field. 


Offset to update password. The offset, in bytes, from the start of the input data area to the update 
password field. 


Parent distinguished name. The parent distinguished name for published objects. For example, if the 
parent distinguished name is "ou=rochester, o=ibm, c=us", a published directory object for user John Smith 
might be "cn=john smith, ou=rochester, o=ibm, c=us". This field is specified in UCS-2 (CCSID 13488). To 
leave the value unchanged, specify a length and offset to this field of zero. 


Password format. The format of the encrypted password. The following values may be specified: 
-1 The value of this field does not change. 
I Unencrypted. 
2 SHA. (Default) 
3 MDS. 
4 Crypt (The password is one-way hashed using a modified DES algorithm. The "crypt" algorithm 
originally was used by many Unix operating systems for password protection.) 


2Projected suffix. The suffix under which all projected objects for this server reside including user and 
group profiles. This field is specified in UCS-2 (CCSID 13488).%& 


Publishing agent name. The agent that will publish information to a directory server and parent 
distinguished name. This field is specified in UCS-2 (CCSID 13488). 


Read only. Whether the directory server will allow updates to be made to the directory contents. The 
following values may be specified: 


-1 The value of this field does not change. 


0 Places the directory server into update mode to allow directory updates. This is the normal mode of 
operation. 


I Places the directory server into read-only mode. 


Referral port. An optional port number to be returned to a client when a request is made for a directory 
object that does not reside on this server. The referral port and referral server together are used to form a 
referral URL. The referral server and port fields must be configured when changing the Server is replica 
field to make this server a replica. Valid port numbers are in the range 1 to 65535. 


Starting with V4R5M6O, this field is ignored for format CSVRO100. Referral server information can be 
changed using the CSVR0600 format of the QgldChgDirSvrA API. The following special values may be 
specified: 


O No port number is returned as part of the referral. 


-1 The value of this field does not change. 


Referral server. The IP name or address of a server to return to a client when a request is made for a 
directory object that does not reside on this server. The referral port and referral server are used together to 
form a referral URL. The referral server and port fields must be configured when changing the Server is a 
replica field to make this server a replica. In this case, the referral is typically to the master server. The 
following special value may be specified: 


*NONE_ No value is specified. 


Note: Starting with V4R5M0O, this field is ignored for format CSVRO100. This field is specified in UCS-2 
(CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. 


Referral server URL. The uniform resource locator (URL) of the referral server. This field is specified in 
UCS-2 (CCSID 13488). 


Reserved. A reserved field. This field must be set to zero. 


Schema checking level. The level of schema checking performed by the server. The following values may 
be specified: 


-1 The value does not change. 
O None. 

I LDAP version 2. 

2 LDAP version 3 strict. 


3 LDAP version 3 lenient. 


Search size limit. The maximum number of entries that the server will return for a given search request. 
The following special values may be specified: 


-1 The value of this field does not change. 


0O Do not limit the number of entries returned. 


Search time limit. The maximum time, in seconds, that the server will spend performing a given search 
request. The following special values may be specified: 


-1 The value of this field does not change. 


O Do not limit the search time. 


Security. Whether the server should use encrypted connections. The following values may be specified: 
-1 The value does not change 
I Allow nonencrypted connections only 
2 Allow encrypted connections only 


3 Allow both encrypted and nonencrypted connections 


Security audit option for objects. When the QAUDCTL system value is set to *OBJAUD, then object 


auditing can be done in the directory. See the iSeries Security Reference Pook for information about 
Directory Services auditing. The following special values may be specified: 


-1 The value of this field does not change. 
0 Do not do object auditing of the directory objects. 


I Audit changes to directory objects. 


2 Audit all access to directory objects. This includes search, compare and change. 


Server is replica. Whether the server is a master server or a replica server. When this field is changed to 
make the server a replica, the update DN, update password, and referral fields must be specified. The 
following values may be specified: 


-1 The value of this field does not change. 
O The server is a master for the directory suffixes present on the server. 


I The server is a replica server for the directory suffixes present on the server. 


Server name. The name of the server. This field is specified in UCS-2 (CCSID 13488). To leave the value 
unchanged, specify a length and offset to this field of zero. 


SSL authentication method. The method used during SSL authentication. The following values may be 
specified: 


-1 The value does not change. 
I Server authentication. 


3 Server and client authentication. 


Suffix. The name of the directory suffix to be added or removed from the server. This field is specified in 
UCS-2 (CCSID 13488). 


Suffix change entries. The list of suffixes to be added or deleted. 
Terminate idle connections. The server will terminate idle connections when necessary. 


Starting with V5R1M6O, this field is no longer supported and is ignored if a value is passed. The following 
values may be specified: 


O Do not terminate idle connections. 


1 Terminate idle connections. 


Transaction time limit. The maximum time, in seconds, that the server will spend performing a transaction 
request. Transaction support allows a group of directory changes to be handled as a single transaction. The 
following special values may be specified: 


-1 The value of this field does not change. 


Update DN. The distinguished name that the master server must use when propagating directory updates to 
this replica server. This field may be specified only when the server is a replica. When either the update DN 
or the update password field is changed, both must be specified. This field is specified in UCS-2 (CCSID 
13488). The following special value may be specified: 


*NONE No value is specified. 


To leave the value unchanged, specify a length and offset to this field of zero. 


Update password. The password used when connecting to this server using the update DN. This field may 
be specified only when the server is a replica. When either the update DN or the update password field is 


changed, both must be specified. This field is specified in UCS-2 (CCSID 13488). To leave the value 


unchanged, specify a length and offset to this field of zero. The following special value may be specified: 


*NONE _ No value is specified. 


Error Messages 


Message ID 
CPF2209 E 
CPFA0A9 E 
CPFAODB E 
CPFA314 E 
GLD0204 E 
GLD0205 E 
GLD0208 E 
GLD0209 E 
GLD020A E 
GLD020B E 
GLD020D E 
GLDO020E E 
GLD0211 E 
GLD0212 E 
GLD0215 E 
GLD0217 E 
GLD0219 E 
GLD021A E 
GLD021B E 
GLD021C E 


GLD021D E 
GLDO21E E 
GLD021F E 


Error Message Text 

Library &1 not found. 

Object not found. 

Object name not a QSYS object. 

Memory allocation error. 

Attribute name not valid. 

Administrator DN not valid. 

Key ring file name not valid. 

Update DN not valid. 

Suffix not valid. 

Referral server name not valid. 

Index rule already defined for attribute. 

Index rule not found for attribute. 

Value &1 specified at offset &2 in input format &3 is not valid. 
Field &1 required when server is using SSL. 

Directory Services server has not been configured. 

A value was specified in list entry &1 that is not valid. Reason code &2. 
Administrator DN and password both required. 

Field not allowed when server is not a replica. 

Field is required when server is a replica. 


The caller of the API must have *ALLOBJ and *IOSYSCFG special authority to 
configure the server. 


Error occurred when processing the input list of entries. 
&1 password is not valid. 


The caller of the API must have *AUDIT special authority to set the server auditing 
information. 


GLD0221 E 
GLD0222 E 
GLD0223 E 
GLD0227 E 
GLD0229 E 
GLD022D E 
GLD022E E 
GLD022F E 


2 GLD0231 E 


GLD0232 E 
GLD0233 E 
GLD0235 E 
GLD0236 E 


Offset &1 specified in input data is not valid. 

Length &1 specified in input data is not valid. 

Database path not valid. 

Distinguished names cannot be modified while the server is active. 
Validation list not found. 

Publishing &1 agent not found. 

Publishing agent &1 is already configured. 

Format not supported. 

Cannot set the password for a projected user. 

Configuration contains overlapping suffixes. 

Cannot set database library to /QSYS.LIB/QUSRDIRCL.LIB. 
IP address is not valid. 


Database library must be in system ASP or basic user ASP.*& 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Export LDIF File (QgidExportLdif) 


Required Parameter Group: 


Input data Char(*) 
Length of input data Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDUAPI 


Threadsafe: No 


The Export LDIF File (QgldExportLdif) API exports the directory server contents to a Lightweight 
Directory Access Protocol Data Interchange Format (LDIF) file. 


Authorities and Locks 


Directory Authority 


The caller must provide the administrator DN and password if the caller does not have *ALLOBJ 
and *IOSYSCFG special authorities and the caller is not a Directory Services administrator. The 
caller is a Directory Services administrator if the Directory Services server has been configured to 
grant administrator access to authorized users and the caller is authorized to the 'Directory Services 
Administrator’ function of the operating system. 


Object Authorities 


The caller must have Execute (*X) authority to each directory in the path name preceding the name 
of the LDIF file. The caller must have Write (*W) authority to the LDIF file. 


Required Parameter Group 


Input data 
INPUT; CHAR(*) 


Input data required to identify the LDIF file and the administrator name and password. The content 
and format of this structure are determined by the format name. See Format of Input Data for a 


description of these formats. 


Length of input data 
INPUT; BINARY(4) 


The length of the input data structure. 


Format name 


INPUT; CHAR(8) 
The content and format of the input data. The possible format name follows: 


LDIFO100_ Export LDIF file. 


See Format of Input Data for a description of this format. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Input Data 


For details about the format of the input data, see the following section. For details about the fields in each 
format, see Field Descriptions. 


LDIFO100 Format 


[Offset 
Lae c | Hex |Type Field 


| | [BI NARY(4) [Offset to LDIF file 


BINARY(4) Length of LDIF file 


| 4 
8 | 8 BINARY(4) Offset to administrator DN 
| C [BIN ARY(4) Length of administrator DN 


| 16 | 10 =|BINARY(4) Offset to administrator password 
| 20 | 14. |BINARY(4) Length of administrator password 


ene 
a 
a ——— 
Se 
Se 
[ 24 | 18 |BINARY@) |Offsetto subtreeDN—~—~S~S~S~*S 
eee 
os _ 
<—e——— 
ee 
Rete 


[ 28 [ Ic BINARY(4) Length of subtree DN 
[| |CHAR@) [LDIF file 
[ [CHAR(*) Administrator DN 
[> [eware) 


Field Descriptions 


Administrator DN. The distinguished name of the server administrator. This field is specified in UCS-2 
(CCSID 13488). 


Administrator password. The password for the server administrator. This field is specified in UCS-2 
(CCSID 13488). 


LDIF file. The integrated file system path name of the LDIF file to be used. This field is specified in 
UCS-2 (CCSID 13488). 


Length of administrator DN. The length, in Unicode characters, of the administrator DN field. 


Length of administrator password. The length, in Unicode characters, of the administrator password 
field. 


Length of LDIF file. The length, in Unicode characters, of the LDIF file field. 
Length of subtree DN. The length, in Unicode characters, of the subtree DN field. 


Offset to administrator DN. The offset, in bytes, from the start of the input data to the administrator DN 
field. 


Offset to administrator password. The offset, in bytes, from the start of the input data to the administrator 
password field. 


Offset to LDIF file. The offset, in bytes, from the start of the input data to the LDIF file field. 

Offset to subtree DN. The offset, in bytes, from the start of the input data to the subtree DN field. 

Subtree DN. The distinguished name (DN) of the root of a directory subtree to export to the LDIF file. 
This object, and all descendant objects will be exported. To export the entire directory tree, specify 0 (zero) 


for the offset to subtree DN and length of subtree DN fields. This field is specified in UCS-2 (CCSID 
13488). 


Error Messages 


Message ID Error Message Text 

GLD0202 E Administrator DN or password not correct. 

GLD0213E Error opening or creating file. 

GLD0215E Server has not been configured. 

GLD0218E *ALLOBJ and *IOSYSCFG special authorities required. 
GLD022B E Cannot find object &1. 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Import LDIF File (QgldImportLdif) 


Required Parameter Group: 


Input data Char(*) 
Length of input data Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDUAPI 


Threadsafe: No 


The Import LDIF File (QgldImportLdif) API imports directory server data from a Lightweight Directory 
Access Protocol Data Interchange Format (LDIF) file. 


The Directory Services server must be stopped to use this API. To stop the server, use the End TCP/IP 
Server (ENDTCPSVR SVR(*DIRSRV)) command. 


Authorities and Locks 


Directory Authority 


The caller must provide the administrator DN and password if the caller does not have *ALLOBJ 
and *IOSYSCFG special authorities #and the caller is not a Directory Services administrator. The 
caller is a Directory Services administrator if the Directory Services server has been configured to 
grant administrator access to authorized users and the caller is authorized to the 'Directory Services 
Administrator’ function of the operating system. 


Object Authorities 


The caller must have Execute (*X) authority to each directory in the path name preceding the name 
of the LDIF file. The caller must have Read (*R) authority to the LDIF file. 


Required Parameter Group 


Input data 
INPUT; CHAR(*) 


Input data required to identify the LDIF file and the administrator name and password. The content 
and format of this structure are determined by the format name. See Format of Input Data for a 


description of these formats. 


Length of input data 
INPUT; BINARY(4) 


The length of the input data structure. 
Format name 
INPUT; CHAR(8) 


The content and format of the input data. The possible format name follows: 


LDIFO100 Import LDIF file. 


See Format of Input Data for a description of this format. 


Error code 


1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error code 
parameter. 


Format of Input Data 


For details about the format of the input data, see the following section. For details about the fields in each 
format, see Field Descriptions. 


LDIFO100 Format 


| Offset 
| D c | Hex |Type Field 
IN 


[B NARY(4) Offset to LDIF file 


BINARY(4) Length of LDIF file 


0 
= 

| 8 | 8 BINARY(4) Offset to administrator DN 
| C 


[BINARY(4) Length of administrator DN 

[ 16 [10 |BINARY() [Offset to administrator password —~S~*S 
[ 20 | 14 |BINARYG) _ |Cength of administrator password SS 
P| CHARC) EDF le 


Field Descriptions 


Administrator DN. The distinguished name of the server administrator. This field is specified in UCS-2 
(CCSID 13488). 


Administrator password. The password for the server administrator. This field is specified in UCS-2 


(CCSID 13488). 


LDIF file. The integrated file system path name of the LDIF file to be used. This field is specified in 
UCS-2 (CCSID 13488). 


Length of administrator DN. The length, in Unicode characters, of the administrator DN field. 


Length of administrator password. The length, in Unicode characters, of the administrator password 
field. 


Length of LDIF file. The length, in Unicode characters, of the LDIF file field. 


Offset to administrator DN. The offset, in bytes, from the start of the input data to the administrator DN 
field. 


Offset to administrator password. The offset, in bytes, from the start of the input data to the administrator 
password field. 


Offset to LDIF file. The offset, in bytes, from the start of the input data to the LDIF file field. 


Error Messages 


Message ID Error Message Text 

GLDO0125 E Directory Services failed for reason code &4. 

GLD0202 E Administrator DN or password not correct. 

GLD0213 E Error opening or creating file. 

GLD0215E Server has not been configured. 

GLDO0218E *ALLOBJ and *IOSYSCEKG special authorities required. 
GLD0225 E  &1 items added to directory, &2 items not added. 
GLD0226 E LDAP server is read-only. 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


List Directory Server Attributes 
(QgldLstDirSvrA) 


Required Parameter Group: 


Qualified user space name Input Char(20) 
Format name Input Char(8) 
Error code VO Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDUAPI 


Threadsafe: No 


The List Directory Server Attributes (QgldLstDirSvrA) API retrieves a list of directory server attributes 
including the following: 


e Suffixes present on the server 

e Attribute indexes maintained by the underlying database 

e Network server publishing attributes associated with the LDAP server. 
e =P address information®* 


Authorities and Locks 


User Space Library Authority 
*EXECUTE 

User Space Authority 
*CHANGE 

User Space Lock 


An exclusive, no-read lock is obtained on the list space. 


Required Parameter Group 


Qualified user space name 
INPUT; CHAR(20) 
The user space that is to receive the created list. The first 10 characters contain the user space 


name, and the second 10 characters contain the name of the library where the user space is located. 
The content and format of this space is determined by the format name. See Format of Output Data 


for a description of these formats. 


Format name 


INPUT; CHAR(8) 

The content and format of the data to be retrieved. The possible format names follow: 
LSVRO200 Retrieve a list of suffixes on the server. 
LSVRO300 Retrieve a list of database indexes maintained by the server. 


LSVROS00 Retrieve a list of network server publishing attributes associated with the LDAP 
server. 


LSVRO600 Retrieve a list of referral servers. 


2* LSVRO800 Retrieve a list of IP addresses*& 


See Format of Output Data for a description of these formats. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Output Data 


The user space contains: 
e A user area 
e A generic area 
e An input parameter section 
e A header section 
e A list data section: 
o LSVRO200 
o LSVRO300 
o LSVROS500 
o LSVRO600 
oO #LSVRO800*8 


For details about the user area and generic header, see User Space Format for List APIs. For details about 


the remaining items, see the following sections. For detailed descriptions of the fields in the list that is 
returned, see Field Descriptions. 


When you retrieve list entry information from the list space, do not use the entry size that is returned in the 
generic header. Instead, use the displacement to next entry field that is returned in each list entry. If you do 
not use the displacement to next entry field, the results may not be valid. 


LSVRO0200 Format 


The LSVRO0200 format is used to retrieve a list of the directory suffixes present on this server. 


| Offset 
| Dec | Hex /Type Field 


| 0 | 0 [BIN ARY(4) [Displacement to next entry 
| 4 | 4 [BIN ARY(4) [Displacement to suffix 

| 8 | 8 [BIN ARY(4) [Length of suffix 

| 12 | Cc [BIN ARY(4) [Reserved 

| | [CHAR(*) [Suffix 


LSVRO0300 Format 


The LSVRO0300 format is used to retrieve information about database indexes maintained by the server. The 
indexes are used to speed up retrieval of objects when a directory server client searches for specified object 
attributes. 


Starting with V4R5M0O, this format is not supported. Database index information is to be retrieved using an 
LDAP client or the Directory Management Tool (DMT) starting with V4R5MO. 


| Offset 
a c | Hex |Type Field 


ie ig Om a 
[ 8 [ 8 J|BINARY(4) [Length ofattributename = = 
[| 12 | C  J[BINARY(4) fIndextype 
[16 [| 10 |BINARY@ [Reserved ~~~SOSOC*~CS~S~*~*~S~S 
| | [CHAR(*) [Attribute name 


LSVRO0500 Format 


The LSVRO0500 format is used to retrieve the network server publishing attributes associated with the 
server. 


| Offset 
| D c || Hex Type Field 


a ea BINARY a —————— 


[28 [| IC |BINARY@) |LengihofbindDN—~S~S«S 


LSVRO600 Format 


The LSVR0600 format is used to retrieve a list of referral servers. 


| Offset 
| Dec Hex /|Type Field 


[ 12 | C |BINARY@) [Reserved ~=~SOC~CS~S*S*S 


*LSVRO0800 Format 


The LSVRO0800 format is used to retrieve a list of the IP addresses to which the directory server connects. 


| Offset 
oe c | Hex |Type Field 


; 0 | 0 |BINARY(4)  [Displacementtonextentry = = = == 
| 4 | 4  |BINARY()  [DisplacementtoIPaddress = = 
[| 8 | 8 JBINARY(4)  [LengthofIPaddress = = = = 
| CHAR(*) IP address*®. 


Field Descriptions 


Attribute name. The name of a directory object attribute for which database indexes will be maintained. 
This field is specified in UCS-2 (CCSID 13488). The following special value may also be returned: 


*DEFAULT The rules for this attribute apply to all attributes for which no explicit rules have been 
defined. 


Bind DN. A distinguished name to use when publishing objects to the directory.This field is specified in 
UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


Connection type. The type of connection to use to the LDAP server. The following values may be 
returned: 


1 Nonsecure 


2 Secured, using SSL 


Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the 
attribute name field. 


Displacement to bind DN. The displacement, in bytes, from the start of the current entry to the bind DN 
field. 


2Displacement to IP address. The displacement, in bytes, from the start of the current entry to the IP 
address field.“ 


Displacement to Kerberos key tab file. The displacement, in bytes, from the start of the current entry to 
the Kerberos key tab file field. 


Displacement to Kerberos principal. The displacement, in bytes, from the start of the current entry to the 
Kerberos principal field. 


Displacement to Kerberos realm. The displacement, in bytes, from the start of the current entry to the 
Kerberos realm field. 


Displacement to next entry. The displacement, in bytes, from the start of the current entry to the next 
entry. 


Displacement to parent distinguished name. The displacement, in bytes, from the start of the current 
entry to the parent distinguished name field. 


Displacement to publishing agent name. The displacement, in bytes, from the start of the current entry to 
the publishing agent name field. 


Displacement to referral server URL. The displacement, in bytes, from the start of the current entry to the 
referral server URL field. 


Displacement to server name. The displacement, in bytes, from the start of the current entry to the server 
name field. 


Displacement to suffix. The displacement, in bytes, from the start of the current entry to the suffix. 
Format name specified. The format name specified on the call to this API. 


Index type. The kind of database indexes that will be created for an attribute. Creating database indexes 
improved the performance of directory searches on those attributes. The following values may be returned: 


O No indexes will be created for the attribute. 


I Equal 


“IP address. The IPv4 address on which the directory server will accept connections. An address is 
expressed in standard dotted-decimal form www.xxx.yyy.zzz; for example, 130.99.128.1. This field is 
specified in UCS-2 (CCSID 13488). The following special value may be returned: 


*ALL All IP addresses defined on the local system will be bound to the server.%& 


Kerberos authentication indicator. The following special values may be specified: 
0 Do not support Kerberos authentications. 


I Support Kerberos authentications. 


Kerberos key tab file. The integrated file system path name for the key tab file that contains the server's 
secret key used for authentication. The QDIRSRV user profile is given authorization to read this file. This 
field is specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE _ No value is specified. 


Kerberos principal. The principal in the key tab file to use for authentication. This field is specified in 
UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


Kerberos realm. The realm where the principal is registered to use for authentication. This field is 
specified in UCS-2 (CCSID 13488). The following special value may be specified: 


*NONE No value is specified. 


LDAP port number. The LDAP server's TCP/IP port. 

Length of attribute name. The length, in Unicode characters, of the attribute name field. 
Length of bind DN. The length, in Unicode characters, of the bind DN field. 

Length of IP address. The length, in Unicode characters, of the IP address field.“ 


Length of Kerberos key tab file. The length, in Unicode characters, of the Kerberos key tab file field. 


Length of Kerberos principal. The length, in Unicode characters, of the Kerberos principal field. 
Length of Kerberos realm. The length, in Unicode characters, of the Kerberos realm field. 


Length of parent distinguished name. The length, in Unicode characters, of the parent distinguished 
name field. 


Length of publishing agent name. The length, in Unicode characters, of the publishing agent name field. 
Length of referral server URL. The length, in Unicode characters, of the referral server URL field. 
Length of server name. The length, in Unicode characters, of the server name field. 

Length of suffix. The length, in Unicode characters, of the suffix field. 

Length of update DN. The length, in Unicode characters, of the update DN field. 


Parent distinguished name. The parent distinguished name to be used. This field is specified in UCS-2 
(CCSID 13488). 


Publishing agent name. The agent which will publish information to a directory server and parent 
distinguished name. This field is specified in UCS-2 (CCSID 13488). 


Publishing agent disabled. Indicates whether or not the publishing agent is disabled. The configuration 
data still exists, but publishing has been disabled for the publishing agent. The following values may be 
returned: 


0 The publishing agent is enabled. 
I The publishing agent is disabled. 


Referral server URL. The uniform resource locator (URL) of the referral server. This field is specified in 
UCS-2 (CCSID 13488). 


Reserved. A reserved field. This field must be set to zero. 
Server name. The name of the server. This field is specified in UCS-2 (CCSID 13488). 


Suffix. The directory name for the starting point of a directory information tree.This field is specified in 
UCS-2 (CCSID 13488). 


Error Messages 


Message ID Error Message Text 
CPF24B4E _— Severe error while addressing parameter list. 
GLD0215 E Server has not been configured. 


GLD022F E_ Format not supported. 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Publish Directory Object (QgldPubDirObj) 


Required Parameter Group: 


Input data Char(*) 
Length of input data Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QS YS/QGLDPAPI 


Threadsafe: No 


The Publish Directory Object (QgldPubDirObj) API publishes objects to the directory server. It can be used 
to perform the following publishing requests: 


e Add a new object to the directory. 

e Delete an object from the directory. 

e Change an object in the directory. 

e Change the relative distinguished name of an object in the directory server. 
Before this API can be called, the Directory Services property page for the system must be configured. This 
can be done from iSeries Navigator or by using the Change Directory Server Attributes (QgldChgDirSrvA) 
API. The directory server indicates the server to which objects will be published. The parent distinguished 


name indicates the suffix in the directory to which objects will be published. This parent distinguished 
name is referred to as a publish point. 


Authorities and Locks 


*ALLOBSJ special authority is required to use this API. 


Required Parameter Group 


Input data 
INPUT; CHAR(*) 


A variable that contains the input data. See Format of Input Data for a description of the data 
associated with a specific format name. 


Length of input data 
INPUT; BINARY(4) 


The length of the input data area. The maximum value for this parameter is 16 776 704. 


Format name 
INPUT; CHAR(8) 


The format name identifying the type of publishing request. The possible format names follow: 
POBJO100 Add anew object to the directory server. 
POBJO200 Delete an object from the directory server. 
POBJO300_ Change an object in the directory server. 


POBJ0400_ Change the relative distinguished name of an object in the directory server. 


See Format of Input Data for a description of these formats. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Input Data 


For details about the format of the input data, see the following sections. For details about the fields in each 
format, see Field Descriptions. 


POBJ0100 Format 


This format is used to add a new object to the directory server. 


Offset 
c | Hex |Type Field 


[BINARY(4) [BINARY(4) Offset to publishing agentname = to [Offset to publishing agentname agent name 


| BINARY(4) [Length of publishing agent name 
| 8 BINARY(4) [Offset to object RDN 
x C |BINARY(4) [Length of object RDN 


"a 


| 


BINARY(4) Offset to attribute entries 


lOtsetioaiibueenties 
[BINARY(4) [Number of attribute entries 
= a [CHAR(40) [Reserved 

| | [CHAR(*) [Publishing agent name 

| | |CHAR(*) [Object RDN 

Attribute entries: 

| 0 | 0 |BINARY(4)  [Displacementtonextentry == 


et 


| 16 [ 10 |BINARY(4) [Number of attribute values = 
| 20 | 14 |BINARY(4) [Attribute valuedatatype = 
[24 | 18 |GHAR® [Reserved =~ SOSOSCS~S 
| = [| ~~ JCHARC*)—[Attributemame 
Attribute values: 

[ 0 [| 0 |BINARY(4)  [Displacementtonextvalue = = = 
[| 4 [| 4  |BINARY(@) — [Displacementto attribute value == 
| 8 | 8 J|BINARY() [Length ofattributevaue = = = == 
[12 [| C |GHAR@ [Reserved ~~~SSOSOC~CS 
| [ss CHAR(*) [Attribute value 


POBJ0200 Format 


This format is used to delete an object from the directory server. 


| Offset 
a c | Hex |Type Field 


[8 | 8 |BINARY@) |Offsetto objectRDN.—~—~—~S~S~S 
[ 12 | © |BINARY@) [Length of objectRDN.—~—~S~*S 
[20 | 14 |CHAR@) [Reserved ~~~ SOSCSCS~S~S 
[ [| ——sJCHAR@) —fObjectRDN 


POBJ0300 Format 


This format is used to change an object in the directory server. 


| Offset 
| D c | Hex ae Field 


[| = [  |CHARC(*) [Publishing agentname 
[ [| — |CHAR() ——JObjectRDN 
[Modificationentriess 
| 0 0 nee [Displacement tonextentry = 
Ie [ BINARY CAS [BisIesano ws aE SEE —— 
| 12 [ C  |BINARY() — [Number of attribute entries = 
[| 0 [| 0 |BINARY(4)  [Displacementtonextentry = = == 
| 4 [| 4  |BINARY() — [Displacementto attributename = = 
[8 | 8 (BINARY) |Lengthofattribuename 
| 12 [ C  |BINARY() — [Displacementto attribute values 
2S 6 DO ee 
[ 2 [1 Sane [Reserved 

ate) ie 
Attribute values: 

[| 4 [| 4  |BINARY() — [Displacementto attribute value == 
[12 [| C |GHAR@ [Reserved ~~ SCS 
| So [)—sCHAR(*) [Attribute value 


POBJ0400 Format 


This format is used to change the relative distinguished name (RDN) of an object in the directory server. 


| Offset 
a c | Hex |Type Field 


a NA ton RB 
Sana ee 
[20 | 14 |BINARYG) [Length ofnewobjectRDN. SS 
[ 24 | 18 |BINARYG) [DeleteoldRDN.———~—~SCS~S 
[28 | IC |CHARG6 [Reserved ~~~~SOSC~*~CS 
[| |GHAR@)_NewobjectRDN.—~—~SC~CS~S 


Field Descriptions 


Add object if it does not exist. Create the object if a request is made to modify an object that does not 
exist. The following values may be specified: 


O Do not create the object if it does not exist. 


I Create the object if it does not exist. All required attributes for the object must be specified on the 
API in order for the object to be successfully created. 


Attribute name. The name of a directory object attribute. This field is specified in UCS-2 (CCSID 13488). 
Attribute value. The value of a directory object attribute. 


Attribute value data type. The type of data for the attribute values. The following values may be 
specified. 


I The attribute values are specified in UCS-2 (CCSID 13488). 
2 The attribute values contain binary data. 
3 The attribute values contain integer data. 


4 The attribute values contain boolean data. 


Change type. The type of change being made to a directory object. The following values may be specified: 
I Adda new attribute 

Delete an attribute 

Replace an attribute 

Add an attribute if it does not exist 

Add an attribute value if it does not exist 


Delete an attribute if it exists 


N DHA WwW KR WwW WN 


Delete an attribute value if it exists 


Delete directory subtree. The directory object and any child directory objects should be deleted. The 
following values may be specified: 


O Do not delete the directory subtree. Only the directory object itself will be deleted. 
I Delete the directory subtree. 


2 Delete the directory subtree. The root of the subtree will not be deleted. 


Delete old RDN. The old relative distinguished name (RDN) of a directory object should be deleted. The 
following values may be specified: 


0 Do not delete the old RDN. The old RDN attribute value will be retained as an attribute of the object. 


1 Delete the old RDN. 


Displacement to attribute entries. The displacement, in bytes, from the start of the current entry to the 
attribute entries. 


Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the 
attribute name field. 


Displacement to attribute value. The displacement, in bytes, from the start of the current entry to the 
attribute value field. 


Displacement to attribute values. The displacement, in bytes, from the start of the current entry to the 
attribute values. 


Displacement to next entry. The displacement, in bytes, from the start of the current entry to the next 
entry in the input data. 


Displacement to next value. The displacement, in bytes, from the start of the current value to the next 
value in the input data. 


Length of attribute name. The length, in Unicode characters, of the attribute name field. 

Length of attribute value. The length of the attribute value field. If the attribute value is specified in 
UCS-2 (CCSID 13488), this is the length in Unicode characters. If the attribute value contains binary data, 
this is the length in bytes. If the attribute value contains integer or boolean data, this field must contain the 
value 4. 

Length of new object RDN. The length, in Unicode characters, of the new object RDN field. 

Length of object RDN. The length, in Unicode characters, of the object RDN field. 


Length of publishing agent name. The length, in Unicode characters, of the publishing agent name field. 


New object RDN. The new relative distinguished name (RDN) of the directory object. This field is 
specified in UCS-2 (CCSID 13488). 


Number of attribute entries. The number of attribute entries. 


Number of attribute values. The number of attribute values. 


Number of modification entries. The number of modification entries. 


Object RDN. The relative distinguished name (RDN) of the directory object being published. This name, 
combined with the publishing point specified during configuration, form a distinguished name (DN). This 
field is specified in UCS-2 (CCSID 13488). For example, if the publishing point is 'O=ACME Corp., 
C=US' and the object RDN is 'CN=Bart’, the object DN to be published is 'CN=Bart, O=ACME Corp., 
C=US'. 


Offset to attribute entries. The offset, in bytes, from the start of the input data area to the attribute entries. 


Offset to modification entries. The offset, in bytes, from the start of the input data area to the modification 
entries. 


Offset to new object RDN. The offset, in bytes, from the start of the input data area to the new object RDN 
field. 


Offset to object RDN. The offset, in bytes, from the start of the input data area to the object RDN field. 


Offset to publishing agent name. The offset, in bytes, from the start of the input data area to the 
publishing agent name field. 


Publishing agent name. The agent making the publishing request. This determines where in the directory 
the object will be published. The publishing agent information must be configured using the 
QegldChgDirSvrA API before calling this API. This field is specified in UCS-2 (CCSID 13488). 


Reserved. A reserved field. This field must be set to binary zero. 


Error Messages 


Message ID Error Message Text 

CPFA314E Memory allocation error. 

CPFB802 E The caller of the API must have *ALLOBJ special authority. 
CPFB803 E_ Publishing agent &1 is not configured or has been disabled. 


CPFB805 E Value specified in input data is not valid. 


API Introduced: V4R4 


Top | Directory Services APIs | APIs by category 


Retrieve Directory Server Attributes 
(QgldRtvDirSvrA) 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 
Format name Char(8) 
Error code Char(*) 


Default Public Authority: *USE 


Library Name/Service Program: QSYS/QGLDUAPI 


Threadsafe: No 


The Retrieve Directory Server Attributes (QgldRtvDirSvrA) API retrieves information about the directory 
server configuration. It can be used to retrieve information about: 


e General server properties 


e Encrypted communications configuration. The Secure Sockets Layer (SSL) is used for encrypted 
communications. 


e Performance settings 


e Auditing settings 


Authorities and Locks 


No OS/400 authority is required for all formats. 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 


The variable to receive output data. See Format of Output Data for a description of the format of 
the output data associated with a specific format name. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable area. 
Format name 
INPUT; CHAR(8) 


The format name identifying the type of information to be retrieved. The possible format names 
follow: 


RSVRO1O0O Basic server configuration 
RSVRO400_ Attributes for publishing users in an LDAP directory 


RSVRO700_ Server auditing information 


See Format of Output Data for a description of these formats. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of Output Data 


For details about the format of the output data, see the following sections. For details about the fields in 
each format, see Field Descriptions. 


RSVR0100 Format 


This format is used to retrieve basic server configuration information. 


| Offset 
| D c | Hex a Field 


ae BINARY) — [Ret ay 
[28 [IC |BINARYG@) [Encrypted port number ——~—~S~S~*S 
[32 | 20 [BINARY@)  |Cumentcipher protocols. ——~—~S~S~S~S 
| 44 | 2C |BINARYG@) |Searchselimt ~~—~—~S~S 


| 68 | 44 |BINARY(4)  [Lengthofreferralserver = = = 
| 72 | 48 |BINARY(4) — Offset to administrator distinguished name (DN) 
| 76 [| 4C |BINARY(4) [Length of administrator DN == 
| 80 | 50 |BINARY(4) |OffsettoupdaeDN = = = 
[ 84 | 54 [BINARY |LengthofupdateDN—~——S™S 
| 88 [| 58 |BINARY(4) [Reserved = = 
| 92 [| 5C |BINARY(4) [Reserved 
| 96 | 60 |BINARY(4)  |Offsettodatabase path == 
| 100 [ 64 |BINARY(4) [Length ofdatabasepath = 
| 112 [ 70 |BINARY(4) — [Number of database connections = 
| 120 | 78 |BINARY(4)  |Offsettomasterserver URL = 
[| 124 [ 7C |BINARY(4) [Length of master server URL 
| 128 [| 80 |BINARY(4)  |Changelogindicator = 
| 132 | 84 |BINARY(4) [Maximum number of change logentries 
| 136 [ 88 |BINARY(4) [Terminate idle connections = 
| 140 | 8C |BINARY(4) [Kerberos authentication indicator = 
| 144 | 90 |BINARY(4)  |Offsetto Kerberoskeytabfile == 
| 148 | Ok BINARY) _ [Length of Kerberos Key wb Ale 
is —[- Se BINARYGS— [OH is Katana 
| 160 [| AO |BINARY(4) [Length of Kerberos administrator ID = 
| 164 [Aa |BINARY(G) [Offset to Kerberos administrator realm 
| 168 | A8 |BINARY(4) — [Length of Kerberos administrator realm 
| 172 [ AC |BINARY(4) — [Event notification registration indicator 
| 176 | BO |BINARY(4) [Maximum event registrations for connection 
[| 184 [ B8 |BINARY(4) [Maximum operations per transaction = 
| 188 | BC |BINARY(4) [Maximum pending transactions = 
| 192 | CO |BINARY(4)  |Transactiontime limit = 
| 196 [ C4 |BINARY(4) [ACLmodel 
| 204 | CC |BINARYG@) [Offsetto projected suffix —~—~SC~S~* 
| | [CHAR(*) [Referral server 

| = [| JCHAR(@) [Database path 
[| | ~~ |CHARC!) —[MasterserverURLs— 


| | |CHAR(*) [Kerberos administrator ID 
[| |CHAR(*) [Kerberos administrator realm 
| a | [CHAR() [Projected suffix®s 


RSVR0400 Format 


This format is used to retrieve the attributes for publishing users in an LDAP directory. User information 
from the system distribution directory can be published to an LDAP server by the Synchronize System 
Distribution Directory to LDAP (QGLDSSDD) API and from iSeries Navigator. The publishing attributes 
define how to publish user information. 


| Offset 
oe c | Hex |Type Field 


St 
[| 4 | 4  |BINARY()  [Bytesavailable = = = = = = 
| 20 [ 14 |BINARY(4) |Connectiontype = == ss— 
| 24 | 18 |BINARY(4) Offset to parent distinguished name. = 
[CHAR(*) [Server name 

[CHAR(*) [Parent distinguishedname. 


RSVRO0700 Format 


This format is used to retrieve server auditing configuration information. 


| Offset 
a Hex |Type Field 


| [BIN ARY(4) [Bytes returned 
| 4 | 4 [BINARY (4) [Bytes available 
| 8 | 8 [BIN ARY(4) [Security audit option for objects 


Field Descriptions 


ACL model. The ACL model that is being used. The following special values may be returned: 


0 The ACL model being used supports access-class level permissions. This is the ACL model the 
directory server used prior to VSR1MO. 


I The ACL model being used supports both access-class level permissions and attribute-level ACL 
permissions. 


Administrator DN. A distinguished name (DN) that has access to all objects in the directory. This field is 
specified in UCS-2 (CCSID 13488). 


Bytes available. The number of bytes of data available to be returned. All available data is returned if 
enough space is provided. 


Bytes returned. The number of bytes of data returned. 


Change log indicator. The indicator of whether a change log exists for entries that have been added, 
changed and deleted. The following values may be returned: 


0 No, achange log does not exist 


I Yes, a change log exists 


Connection type. The type of connection to use to the LDAP server. The following values may be 
returned: 


1 Nonsecure 


2 Secured, using SSL 


Current cipher protocols. The cipher protocols that the server allows when using encrypted connections. 
The value is the sum of zero or more of the following values: 


0x0100 Triple Data Encryption Standard (DES) Secure Hash Algorithm (SHA) (U.S.) 
0x0200 DES SHA (U.S) 

0x0400 Rivest Cipher 4 (RC4) SHA (U:S.) 

Ox0S00 RC4 Message Digest (MD) 5 (U.S.) 

0x1000 RC2 MDS (export) 

0x2000 RC4 MDS (export) 


20x4000 Advanced Encryption Standard (AES) SHA (U.S.)&& 


Database path. The integrated file system path name of the library containing the directory database. This 
field is specified in UCS-2 (CCSID 13488). 


Encrypted port number. The port number to use for encrypted connections. The standard port number for 
encrypted connections is 636. 


Event notification registration indicator. Indicator of whether to allow client to register for event 
notification. The following special values may be returned: 


0 Do not allow clients to register for event notification. 


I Allow clients to register for event notification. 


Installed cipher protocols. The cipher protocols installed on the system. Refer to the current cipher 


protocols field for a description of the values. 


Kerberos administrator ID. The name of the Kerberos administrator. This field is specified in UCS-2 
(CCSID 13488). The following special value may be returned: 


*NONE No value is specified. 


Kerberos administrator realm. The realm in which the kerberos administrator is registered. This field is 
specified in UCS-2 (CCSID 13488). The following special value may be returned: 


*NONE_ No value is specified. 


Kerberos authentication indicator. The following special values may be returned: 
O Do not support Kerberos authentications. 


ZI Support Kerberos authentications. 


Kerberos key tab file. The integrated file system path name for the key tab file that contains the server's 
secret key used for authentication. This field is specified in UCS-2 (CCSID 13488). The following special 
value may be returned: 


*NONE No value is specified. 


Kerberos to DN mapping indicator. 


O Map the Kerberos ID to pseudo DN. A pseudo DN can be used to uniquely identify an LDAP user 
object of the form 'ibm-kerberosName=principal @realm’ or 'ibm-kn=principal @realm'’. 


I Use associated DN in directory. The LDAP server will attempt to find an entry in the directory that 


contains the kerberos principle and realm as one of its attributes. Once found, this DN will then be 
used to determine the client's authorizations to the directory. 


LDAP port number. The LDAP server's TCP/IP port. 
Length of administrator DN. The length, in Unicode characters, of the administrator DN field. 
Length of database path. The length, in Unicode characters, of the database path field. 


Length of Kerberos administrator ID. The length, in Unicode characters, of the Kerberos Administrator 
ID field. 


Length of Kerberos administrator realm. The length, in Unicode characters, of the Kerberos 
administrator realm field. 


Length of Kerberos key tab file. The length, in Unicode characters, of the Kerberos key tab file field. 
Length of master server URL. The length, in Unicode characters, of the master server URL field. 


Length of parent distinguished name. The length, in Unicode characters, of the parent distinguished 
name field. 


“Length of projected suffix. The length, in Unicode characters, of the projected suffix field 
Length of server name. The length, in Unicode characters, of the server name field. 


Length of referral server. The length, in Unicode characters, of the referral server field. 


Length of update DN. The length, in Unicode characters, of the update DN field. 
2*Level of authority integration. The level of OS/400 authority integration to use to determine if a 
distinguished name (DN) can become an LDAP administrator. The following special values may be 


specified: 


0 Do not apply 'Directory Services Administrator’ (QIBM_DIRSRV_ADMIN) function identifier to 
bound distinguished names to determine LDAP administrators. 


ZI Allow bound distinguished names that refer directly to user profiles to become LDAP administrators 
if the user profile is identified in the 'Directory Services Administrator’ (QIBM_DIRSRV_ADMIN) 
function identifier. 


Master server URL. The uniform resource locator (URL) of the master server. This field is specified in 
UCS-2 (CCSID 13488). The following special value may be returned: 


*NONE No value is specified. 


Maximum connections. Returns the maximum number of simultaneous connections that can be 
established with the server. 


Starting with V5R1M6O, this field is no longer supported and the value returned is 0. The following special 
value may be returned: 


O Do not limit the number of connections. 


Maximum event registrations for connection. The following special values may be returned: 


0 Do not limit the number of event registrations for connection. 


Maximum event registrations for server. The following special values may be returned: 


O Do not limit the number of event registrations for server. 


Maximum number of change log entries. The maximum number of change log entries that can be stored. 
If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value 
only valid if 'Change log indicator’ is set to 1. The following special values may be returned: 


O The number of change log entries is not limited. 


Maximum operations per transaction. The maximum number of operations that are allowed for each 
transaction. Transaction support allows a group of directory changes to be handled as a single transaction. 


Maximum pending transactions. The maximum number of pending transactions allowed. Transaction 
support allows a group of directory changes to be handled as a single transaction. 


Number of database connections. The number of database connections used by the server. 


Offset to administrator DN. The offset, in bytes, from the start of the receiver variable to the administrator 
DN field. 


Offset to database path. The offset, in bytes, from the start of the receiver variable to the database path 
field. 


Offset to Kerberos administrator ID. The offset, in bytes, from the start of the input data area to the 


Kerberos administrator ID field. 


Offset to Kerberos administrator realm. The offset, in bytes, from the start of the input data area to the 
Kerberos administrator realm field. 


Offset to Kerberos key tab file. The offset, in bytes, from the start of the input data area to the Kerberos 
key tab file field. 


Offset to master server URL. The offset, in bytes, from the start of the receiver variable to the master 
server URL field. 


Offset to parent distinguished name. The offset, in bytes, from the start of the receiver variable to the 
parent distinguished name field. 


Offset to projected suffix. The offset, in bytes, from the start of the input data area to the projected 
suffix field. 


Offset to referral server. The offset, in bytes, from the start of the receiver variable to the referral server 
field. 


Offset to server name. The offset, in bytes, from the start of the receiver variable to the server name field. 
Offset to update DN. The offset, in bytes, from the start of the receiver variable to the update DN field. 


Parent distinguished name. The parent distinguished name for published objects. For example, if the 
parent distinguished name is 'ou=rochester, o=ibm, c=us', a published directory object for user John Smith 
might be 'cn=john smith, ou=rochester, o=ibm, c=us'. This field is specified in UCS-2 (CCSID 13488). 


Password format. The format of the encrypted password. The following values may be returned: 
ZI Unencrypted. 
2 SHA. (Default) 
3 MDS. 
4 Crypt (The password is one-way hashed using a modified DES algorithm. The ‘crypt’ algorithm 
originally was used by many UNIX operating systems for password protection.) 


2Projected suffix. The suffix under which all projected objects for this server reside including user and 
group profiles. This field is specified in UCS-2 (CCSID 13488).*& 


Read only. Whether the directory server allows changes to be made to the directory contents. The 
following values may be returned: 


0 The directory server is not read only. Updates are allowed to the directory. 


I The directory server is read only. Updates are not allowed to the directory. 


Referral port. An optional port number to be returned to a client when a request is made for a directory 
object that does not reside on this server. The referral port and referral server together are used to form a 
referral URL. The following special value may be returned: 


0 The LDAP port is not specified, the client should use the default LDAP port. 


Referral server. The IP name of a server to return to a client when a request is made for a directory object 
that does not reside on this server. This field is specified in UCS-2 (CCSID 13488). The referral port and 


referral server are used together to form a referral URL. The following special value may be returned: 


*NONE No value is specified. 


Reserved. A reserved field. This field must be set to zero. 


Schema checking level. The level of schema checking performed by the server. The following values may 
be returned: 


O None. 
Il LDAP version 2. 
2 LDAP version 3 strict. 


3 LDAP version 3 lenient. 


Search size limit. The maximum number of entries that the server will return for a given search request. 
The following special value may be returned: 


O Do not limit the number of entries returned. 


Search time limit. The maximum time, in seconds, that the server will spend performing a given search 
request. The following special value may be returned: 


0 Do not limit the search time. 


Security. Whether the server is to use encrypted connections. The following values may be returned: 
0 Allow unencrypted connections only. 
I Allow encrypted connections only. 


2 Allow both encrypted and unencrypted connections. 


Note: SSL is used for encrypted connections to the server. 


Security audit option for objects. When the QAUDCTL system value is set to *OBJAUD, then object 


auditing can be done in the directory. See the iSeries Security Reference P book for information about 
Directory Services auditing. The following special values may be returned: 


0 Do not do object auditing of the directory objects. 
ZI Audit changes to directory objects. 


2 Audit all access to directory objects. This includes search, compare and change. 


Server is replica. Whether the server is a master server or a replica server. The following values may be 
returned: 


0 The server is a master server for the directory suffixes present on the server. 


1 The server is a replica server for the directory suffixes present on the server. 


Server name. The name of the server. This field is specified in UCS-2 (CCSID 13488). 


SSL authentication method. The method used during SSL authentication. The following values may be 
returned: 


1 Server authentication. 


3 Server and client authentication. 


Terminate idle connections. The server will terminate idle connections when necessary. The following 
values may be returned: 


O Do not terminate idle connections. 


1 Terminate idle connections. 


Note: Starting with VSR1MO, this field is no longer supported and the value returned is 0. 


Transaction time limit. The maximum time, in seconds, that the server will spend performing a transaction 
request. Transaction support allows a group of directory changes to be handled as a single transaction. 


Unencrypted port number. The port number to be used for unencrypted connections. The standard port 
number is 389. 


Update DN. The distinguished name that the master server must use when propagating directory updates to 
this replica server. This field is specified in UCS-2 (CCSID 13488). The following value may be returned: 


*NONE_ No value is specified. 


Use encrypted connections. Whether this server should use encrypted connections when making updates 
to the replica server. The following values may be returned: 


O Use unencrypted connections. 


I Use encrypted connections. 


Version. Returns the version of the LDAP server. 


Error Messages 


Message ID Error Message Text 
CPFA314E Memory allocation error. 


GLD0215E Server has not been configured. 


API Introduced: V4R3 


Top | Directory Services APIs | APIs by category 


Synchronize System Distribution Directory to 
LDAP (QGLDSSDD) 


Required Parameter Group: 


Option Char(10) 
LDAP user ID Char(1024) 
LDAP user ID password Char(128) 
No longer used Char(1024) 


No longer used Char(128) 
Error Code Char(*) 


Default Public Authority: “EXCLUDE 


Threadsafe: No 


The Synchronize System Distribution Directory to LDAP (QGLDSSDD) API publishes system distribution 
directory entries to an LDAP directory and keeps the LDAP directory synchronized with changes made in 
the system distribution directory. The following users from the system distribution directory are published: 


e Local users 


e Remote users that have been added to the local system and have a Simple Mail Transfer Protocol 
(SMTP) address 


The system distribution directory users that are not published are: 
e Shadowed users 


e Remote users that do not have a SMTP address 


The Directory Services property page must be set up. In V4R4 and later, users are automatically published 
when you set up users in the Directory Services property page for the LDAP server to publish under. Prior 
to V4R4, this API (QGLDSSDD) must be called regularly to publish the users because publishing users is 
not automatic prior to V4R4. See Usage Notes for the procedures for setting up the Directory Services 


property page. 


If you are using SSL, the SSL key database information is configured using Digital Certificate Manager. 
See Usage Notes for information on accessing the Digital Certificate Manager. 


When using a V4R4 or later iSeries Navigator client to publish users to a V4R4 or later server, the 
following no longer applies because this is done automatically. The synchronization is restricted to one 
LDAP server and one distinguished name to publish to. If you need to change the LDAP server or 
distinguished name that the system distribution directory information gets published to, first end the 
synchronization (using option value *END). Then change the LDAP server attributes from iSeries 
Navigator or from the Change Directory Server Attributes (QgldChgDirSrvA) API. You can then use 
option *ALL to initialize all the system distribution directory data to the new LDAP server or distinguished 
name. 


Before users can be published, the host and domain name must be set using the Change TCP/IP Domain 
(CHGTCPDMN) command. The keywords that must be set ace HOSTNAME and DMNNAME. 


LDAP uses the distinguished name (dn) as the key for the user. For the system distribution directory entries 
in LDAP, the distinguished name is the common name (cn) combined with the distinguished name that 
LDAP is being published to. See Distinguished Name (dn) and Common Name (cn) for more information. 


Note that if changes are made in the LDAP directory, these changes are not synchronized back to the 
system distribution directory. 


Some entries are automatically prevented from being published to LDAP. They are the *ANY system 
distribution directory entries and some other entries that are IBM-supplied starting with Q (QSECOFR, 
QDOC, QSYS, QDFTOWN, QUSER for example). A specific user can be prevented from being published 
to LDAP by doing the following: 


1. Add the user-defined field QREPL QLDAP to the system distribution directory. This needs to be 
done only once per system. 


CHGSYSDIRA USRDFNFLD((QREPL QLDAP *ADD *DATA 4) ) 


2. Specify *NO as the value for the QREPL QLDAP user-defined field for those users that you do not 
want to replicate to LDAP. Any other value or absence of the QREPL QLDAP user-defined field 
will replicate the user. It is recommended that you either leave the QREPL QLDAP value blank or 
specify *YES if you want the user to be replicated. 


For example, using Work with Directory Entries (WRKDIRB), option | to add a user or option 2 to 
change a user, press the F20 key to specify user-defined fields. When using the ADDDIRE or 
CHGDIRE commands, specify USRDFNFLD((QREPL QLDAP *NO)) to prevent the user from 
being replicated. 


3. If the user is already replicated to LDAP, and *NO is specified in the QREPL QLDAP user-defined 
field, then the user will be deleted from the LDAP directory. Likewise, if the value of the QREPL 
QLDAP user-defined field is changed to anything but *NO, then the user will be added to the 
LDAP directory. 


As an administrator, you must understand some additional items that are needed to synchronize the system 
distribution directory to LDAP. These include the following: 


e@ inetOrgPerson and publisher object classes used in synchronization. 
e How the system distribution directory fields map to LDAP attributes. 
e What is a distinguished name and common name and why they are important for synchronization. 


e How the OS/400 user profile field is used in LDAP. 


See Directory Services (LDAP): Question and Answers! for additional information on publishing users. 


inetOrgPerson and publisher Object Class 


If your LDAP server is not on OS/400, you must ensure that the inetOrgPerson and publisher object classes 
are defined in the schema file of the server. The inetOrgPerson object class is used in LDAP to store the 
system distribution directory information. The publisher object class requires a new attribute, 


publisherName. See SecureWay Directory Schema“ for documentation on the inetOrgPerson and 
publisher object class. 


System Distribution Directory to LDAP Mapping 


The system distribution directory entry is published to the LDAP directory by using the inetOrgPerson 
object class. The following table describes the mapping of system distribution directory fields to attributes 
of the inetOrgPerson object class. 


[Table 1: System Distribution Directory Fields Mapped to LDAP Attributes 
[System Distribution Directory Field [LDAP Attribute = 
[Userprofile ———SUD 
[Descriptions =————<—~s—SCSCS description 
[Firstname = =———itsé‘“‘;SCSC~ CL ivenName, cn (Common ame) 
[Preferredname  =————s—<~*~‘—~:*C~*Mcn (COMMON MAM) 
[Fullname = =——ss—<“—~s—ssCCC— Cn (COMMON MAME) 
[UserID = on (commonname) 
[Department = =====—[departmentNumber 
Jobtitle tite 
[Telephone number1&2 = =———si[telephoneNumber 
[FAX telephone number facsimileTelephoneNumber 

[Office = —sSsrtocomNmber 
[Address lines 1-4 sregisteredAddress 
[SMTPname ——s—CSi mand 


If the field is blank in the system distribution directory, then the attribute is not created in LDAP for that 
user, with the following exceptions: 


e Last name: If last name is blank, then the user ID is used in the LDAP directory for the surname 
(sn) attribute. 


e@ SMTP name: When a user has a SMTP name, the SMTP userID (SMTPAUSRID) and SMTP 
domain (SMTPDMN), or SMTP route (SMTPRTE) is used in the following format: 
SMTPAUSRID @SMTPDMN or SMTPRTE if they just have a route. For local users, if the SMTP 
name is blank, then the User ID and address fields are used for the mail attribute in the format 
"UserID? Address @ Domain’. Domain is the value specified on the Change TCP/IP Domain 
(CHGTCPDMN) command and the '?' is the default SMTP User ID delimiter value specified on the 
Change SMTP Attributes (CHGSMTPA) command. 


Distinguished Name (dn) and Common Name (cn) 


LDAP uses the distinguished name (dn) as the key for the user. For the system distribution directory entries 
in LDAP, the distinguished name is the common name (cn) combined with the distinguished name that 
LDAP is being published to. 


The user will have the following common names in LDAP. The first nonblank one will be used in the 
distinguished name: 


1. 'First name' "Middle Name' 'Last name' 


2. 'Preferred name' ‘Last name' 
3. ‘Full name’ 
4. 'UserID' 


For example, if a user has the following field values in the system distribution directory, 
e First name: Jonathan 
e Middle name: T. 

Preferred name: John 

Last name: Smith 

Full name: Smith, John T. 


e 
e 
e 
e User ID: JSMITH 


the user will have the following common names (cn): 
e cn=Jonathan T. Smith 
e cn=John Smith 
e cn="Smith, John T." 
e cn=JSMITH 


If the distinguished name that LDAP is being published to is 'ou=chicago,o=acme,c=us’, then the 
distinguished name of this user is 'cn=Jonathan T. Smith,ou=chicago,o=acme,c=us' using the first cn in the 
list. The cn value is enclosed in quotation marks if it contains a comma, pound sign, plus sign, equal sign, 
less than or greater than sign, or a semicolon. Leading blanks from the system distribution directory fields 
are removed for the cn value. For example, if the first name is ' Jane’, the cn value will use ‘Jane’. Also, the 
system distribution directory field values containing quotation marks will not be used when deriving the cn 
values as described above. 


Attention: If you have two users in the system distribution directory that will resolve to the same 
distinguished name, they will overlay each other in the LDAP directory. Sometimes overlaying names is 
what you want if you are merging multiple system distribution directories into one LDAP directory. If you 
have different users with the same name, ensure they have different distinguished names to prevent 
overlaying each other. 


This API can run on other OS/400 systems to synchronize the system distribution directory on those 
systems to the same LDAP server and distinguished name being published to. If you have the same user on 
multiple OS/400 systems, they will become one user in the LDAP directory. The distinguished name (dn) 
identifies the user. Note that you can run this API from multiple OS/400 systems to different directory 
servers or to the same directory server, but different distinguished name that LDAP is being published to. 
You may want to do this if you would like to ensure that information from different system distribution 
directories does not overlay each other. 


User Profile (UID) for OS/400 Users 


For local users, the user profile field is used to set the UID attribute in the LDAP directory. This API does 
not publish passwords for security reasons. Therefore, when the LDAP server is on an OS/400, the UID 
attribute is used to see if that user exists on the OS/400. The password is verified with the password that is 
passed from the client. 


If you are publishing the system distribution directory information to a different OS/400 or to a system that 
is not an OS/400, then you will need to set the userPassword attribute for those users that you want to 
access the LDAP directory. You would set the userPassword attribute for the user after you use the 


QGLDSSDD API to publish the system distribution directory users. The following shows a client command 
from a UNIX shell that is used to set the userPassword attribute of two users: 


ldapmodify -h ldapserver -f /path/filename 
-D cn=Admin -w password 


The Idapserver is the server name that was configured in the Directory Services system property. The 
/path/filename file contains the distinguished name and password for the users. An example file with two 
user entries would be: 


dn:cn=Jonathan T. Smith, ou=chicago, o=acme, c=us 
changetype: modify 

replace: userPassword 

userPassword:secret 


dn:cn=Barb Jones, ou=chicago, o=acme, c=us 
changetype: modify 

replace: userPassword 
userPassword:secret 


Authorities and Locks 


*ALLOBJ and *IOSYSCFG special authority is required to use this API. 


Required Parameter Group 


Option 
INPUT; CHAR(10) 


The option to use for publishing system distribution directory information to the LDAP directory. 
The valid values are: 


*ALL All the local users and all the remote users that have been added from this system and 
that have an SMTP name will be replicated from the system distribution directory to 
the LDAP directory. The LDAP directory is on the LDAP server specified in the 
Directory Services dialog of iSeries Navigator. These users will be placed in the 
LDAP tree under the distinguished name that is specified in the Directory Services 
dialog. See Table 1 for information concerning the system distribution directory fields 


that will be used in the LDAP directory. 


The *ALL option value also sets up the necessary objects needed to synchronize the 
system distribution directory changes to the LDAP directory after the LDAP directory 
is replicated. 


You must request the *ALL option value first, but it can be specified more than once. 
For example, to reload the LDAP directory, you would use the *CHG option value to 
send any pending changes to the LDAP directory followed by the *ALL option value. 
If you change which LDAP server or distinguished name you want the system 
distribution directory entries to be replicated to, you can use the *ALL option value to 
replicate to that server or distinguished name. 


*CHG The system distribution directory entries that were added, changed, removed, or 
renamed since the *ALL or previous *CHG option value was used are updated in the 
LDAP directory. 


Changes made to the system distribution directory users in the LDAP directory are 
overwritten by changes made in the system distribution directory for the attributes 
listed above. All other attributes of inetOrgPerson that are changed in LDAP by using 
an LDAP client are not overwritten by the *CHG option value. 


*END End the synchronization of the system distribution directory to LDAP. 


If the LDAP user ID is passed in, then this first synchronizes any changes from the 
system distribution directory to the LDAP directory since the last synchronization 
request. For example, 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*END 'LDAPuserID' 'LDAPpassword' 0 0 0) 


If the LDAP user ID is not passed in, then the synchronization is just ended and the 
changes left in the queue from the last synchronization request are not published. For 
example, 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*END 0 0 0 0 0) 


The users in the LDAP directory where publishing is being ended are not deleted. 
They are left in the LDAP directory. Changes made to the system distribution 
directory after publishing is ended are no longer queued. 


To start replication again after this value is used, call this API with the *ALL option 
value. A *CHG option value will result in an error. 


*RESET Ensures that all the objects exist for this replication function and clears the queue that 
keeps track of the changes made to the system distribution directory. 


Specify zero for the LDAP user ID, LDAP user ID password, key database file, and 
key database password when you use this value. For example, 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*RESET 0 0 0 0 0) 


LDAP user ID 
INPUT; CHAR(1024) 


The LDAP user ID that has administrator authority to add, change, and remove entries in the LDAP 
entry. The valid values are: 


*CFG_ Use the configured LDAP user ID that can be specified when publishing users (using 


iSeries Navigator). To use kerberos authentication, you must configure publishing users 
to authenticate using kerberos. When *CFG is specified for LDAP user ID, then 
depending on what has been configured to authenticate for users will be used whether 
that is an administrator ID and password or Kerberos. 


See Usage Notes for the procedure of configuring the Directory Services property page. 
If the Directory Services property page is not configured, and the *CFG value is passed, 
then error GLD0310 with reason code 12 is signalled. If a value is passed in other than 
*CFG and kerberos authentication was configured, then error GLD0310 will occur. 


A null-terminated string containing the LDAP user ID that has administrator authority to add, 
change, and remove entries in the LDAP entry. 


An example user ID is cn=Admin. Specify a zero-length string if the LDAP server does 
not require authority checking or the option value *RESET is specified. 


LDAP user ID password 
INPUT; CHAR(128) 


The password for the LDAP user ID. The valid values are: 


*CFG_ Use the configured LDAP user ID password that can be specified when publishing users 


(using iSeries Navigator). Specify *CFG if kerberos authentication was configured. 


See Usage Notes for the procedure of configuring the Directory Services property page. 
If the Directory Services property page is not configured, and the *CFG value is passed, 
then error GLD0310 with reason code 12 is signalled. If a value is passed in other than 
*CFG and kerberos authentication was configured, then error GLD0310 will occur. 


A null-terminated string containing the password for the LDAP user ID. 


Specify a zero-length string if the LDAP server does not require authority checking or 
the option value *RESET is specified. 


No longer used (Formerly 'Key database file') 
INPUT; CHAR(1024) 


Specify zero (0) as a placeholder for this parameter as it is no longer used. If a value is specified, it 
will be ignored for compatibility reasons. If you need SSL key database information configured, it 
is now configured using Digital Certificate Manager. See Usage Notes below for more information 


on Digital Certificate Manager. 


No longer used (Formerly 'Key database password’) 
INPUT; CHAR(128) 


Specify zero (0) as a placeholder for this parameter as it is no longer used.If a value is specified, it 
will be ignored for compatibility reasons. If you need SSL key database information configured, it 
is now configured using Digital Certificate Manager. See Usage Notes below for more information 


on Digital Certificate Manager. 


Error code 


1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error code 
parameter. 


Note: All character data is assumed to be represented in the CCSID (coded character set identifier) 
currently in effect for the job. If the CCSID of the job is 65535, the data is assumed to be represented in the 
default CCSID of the job. 


Usage Notes 


If the system distribution directory field values for two users result in the same distinguished name, then 
these names will overlay each other in the LDAP directory. To ensure this does not happen when not 
intended, you must have unique names for your users before you synchronize the system distribution 
directory to an LDAP directory. 


Use the Convert SMTP Names (CVTNAMSMTP) command if you have not already done so to convert the 
Simple Mail Transfer Protocol (SMTP) fields to the system distribution directory. The SMTP information 
is loaded when the option value *ALL is used from this API. If, however, you do not do CVTNAMSMTP 
when you change the SMTP information using the Work with Names for SMTP (WRKNAMSMTP) 
command, those changes do not go to the LDAP directory. After you use the CVTNAMSMTP command, 
the SMTP name is in the system distribution directory in the user-defined fields SMTPAUSRID SMTP, 
SMTPDMN SMTP, and SMTPRTE SMTP. When these fields are updated by using the system distribution 
directory commands (WRKDIRE, ADDDIRE, CHGDIRE), then LDAP is kept synchronized. If you cannot 
do CVTNAMSMTP, then the other option is to periodically use the option value *ALL to reload the LDAP 
directory to update all the system distribution directory information including the SMTP information. 


Synchronization Procedure 


A procedure of synchronizing the system distribution directory with an LDAP directory is as follows: 


1. The Directory Services property page for the LDAP server to publish to must be set up. Use iSeries 
Navigator, select 'Properties' of the system, and then ‘Directory Services’. In V4R4 and later, 
Directory Services will bring up a list of information to publish. Select 'Users' from this list to 
configure this information. If your iSeries Navigator or system is prior to V4R4, then just the 
Directory Services properties are set and no list is displayed. 


The LDAP server to publish to must be specified and must exist. The distinguished name to publish 
under must be specified and must be one the server supports. All the users in the system 
distribution directory will be placed under the distinguished name (DN) that is specified. 


See the Directory Services (LDAP) topic for more information on using iSeries Navigator to 
configure the system properties for Directory Services. 


Configuring the Directory Services property also can be done using the Change Directory Server 
Attributes (QgldChgDirSrvA) API. 


2. If you are synchronizing the system distribution directory to an LDAP server that is not on an 
OS/400, then you need to ensure that the inetOrgPerson and publisher object classes are defined in 
the schema file for the server. The publisher object class requires a new attribute, publisherName, 


so be sure publisherName is also defined in a schema file. See SecureWay Directory Schema“ 
for documentation on the inetOrgPerson and publisher object class. 


3. Ensure the TCP/IP host and domain name are set. Use the Change TCP/IP Domain 


(CHGTCPDMN) command and prompt by using F4. 


. Use Change SMTP Attribute (CHGSMTPA) command to set the user ID delimiter value. You can 
keep the default set to '?'. Be sure you press Enter so the SMTP attributes are created. 


. If you need SSL certificate information configured, it is configured using Digital Certificate 
Manager. You can get to Digital Certificate Manager from iSeries Navigator under 'Network - 
Internet - Digital ID’. 


. If you are on V4R4 or later, and selected 'Users' in the list when configuring Directory Services 
property page, then the system distribution directory users will automatically be published to LDAP 
and you will not need to do the following step. You could optionally call it to reinitialize system 
distribution directory data to an LDAP server if needed. 


Call the Synchronize System Distribution Directory to LDAP API with the *ALL option value. For 
example, from the command line, type: 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*ALL 'LDAPuserID!' 'LDAPpassword' 0 0 0) 


The LDAP user ID must have sufficient authority to add, change, and remove entries in the LDAP 
directory. 


If you have the LDAP user ID and password configured in the Directory Services property page, 
you can call the API using *CFG. For example, from the command line, type: 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*ALL *CFG *CFG 0 0 0) 


For security reasons, it is recommended that you call this API using the *CFG option if the call is 
being logged in a job log. 
. If you are on V4R4 or later, and selected 'Users' in the list when configuring Directory Services 


property page, then the system distribution directory users will automatically be published to LDAP 
and you will not need to do the following step (although you can optionally call it manually). 


Periodically call QGLDSSDD to synchronize the LDAP directory with the system distribution 
directory. The command to synchronize the LDAP directory is: 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*CHG 'LDAPuserID' 'LDAPpassword' 0 0 0) 


If you have the LDAP user ID and password configured in the Directory Services property page, 
you can call the API using *CFG. For example, from the command line, type: 


CALL PGM(QSYS/QGLDSSDD) 
PARM(*CHG *CFG *CFG 0 0 0) 


For security reasons, it is recommended that you call this API using the *CFG option if the call is 
being logged in a job log. 


The CL program can be run from a job schedule entry to automatically run with scheduled 
frequency. Use the Add Job Schedule Entry (ADDJOBSCDE) command or the Work with Job 
Schedule Entries (WRKJOBSCDE) command to automatically schedule jobs. 


Error Messages 


Message ID 
CPF3C90 E 
CPF3CF1 E 
GLD0301 E 
GLD0302 E 
GLD0303 E 
GLD0304 E 


GLD0305 C 


GLD0309 E 
GLD0310 E 
GLDO0311 E 
GLD0312 D 


Error Message Text 

Literal value cannot be changed. 

Error code parameter not valid. 

Error encountered when accessing the LDAP Directory Server. 
Input option *CHG currently unavailable. 

The caller of this API must have &1 and &2 special authorities. 


Unable to export the system distribution directory entry &1 &2 to the LDAP Directory 
Server. 


Synchronization between the system distribution directory and the LDAP directory server 
completed. 


Value not valid for input parameter &1. 
Error occurred with QGLDSSDD API. Reason code &1. 
Input parameter &1 is not valid. Reason code &2. 


Error encountered when setting up a secure connection to an LDAP server. The error 
number is &1. 


API introduced: V4R3 
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